consolidated/stompjs/src/client.ts
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:
constructor(conf: StompConfig)
|
||||||||
Defined in consolidated/stompjs/src/client.ts:666
|
||||||||
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 Example:
Parameters :
|
Public appendMissingNULLonIncoming |
Type : boolean
|
Default value : false
|
Defined in consolidated/stompjs/src/client.ts:269
|
Workaround for a React Native WebSocket bug, where messages containing Enabling this appends a Warning:
Example:
|
Public beforeConnect |
Type : function
|
Defined in consolidated/stompjs/src/client.ts:460
|
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. As of version 5.1, this callback supports Example:
|
Public brokerURL |
Type : string | undefined
|
Defined in consolidated/stompjs/src/client.ts:56
|
The URL for the STOMP broker to connect to.
Example: Use this property to define the broker's WebSocket endpoint. Note:
|
Public connectHeaders |
Type : StompHeaders
|
Defined in consolidated/stompjs/src/client.ts:312
|
Connection headers to be sent during the connection handshake. Keys like Example:
|
Public connectionTimeout |
Type : number
|
Default value : 0
|
Defined in consolidated/stompjs/src/client.ts:107
|
Timeout for establishing STOMP connection, in milliseconds. If the connection is not established within this period, the attempt will fail.
The default is Example:
|
Public debug |
Type : debugFnType
|
Defined in consolidated/stompjs/src/client.ts:574
|
Set a custom debug function to capture debug messages. By default, debug messages are discarded. To log messages to the console, you can use:
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 discardWebsocketOnCommFailure |
Type : boolean
|
Default value : false
|
Defined in consolidated/stompjs/src/client.ts:591
|
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:
Default value: |
Public forceBinaryWSFrames |
Type : boolean
|
Default value : false
|
Defined in consolidated/stompjs/src/client.ts:254
|
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). Example:
|
Public heartbeatIncoming |
Type : number
|
Default value : 10000
|
Defined in consolidated/stompjs/src/client.ts:171
|
Interval (in milliseconds) for receiving heartbeat signals from the server. Specifies the expected frequency of heartbeats sent by the server. Set to Example:
|
Public heartbeatOutgoing |
Type : number
|
Default value : 10000
|
Defined in consolidated/stompjs/src/client.ts:199
|
Interval (in milliseconds) for sending heartbeat signals to the server. Specifies how frequently heartbeats should be sent to the server. Set to Example:
|
Public heartbeatStrategy |
Type : TickerStrategy
|
Default value : TickerStrategy.Interval
|
Defined in consolidated/stompjs/src/client.ts:217
|
Strategy for sending outgoing heartbeats. Options:
Note:
Example:
|
Public heartbeatToleranceMultiplier |
Type : number
|
Default value : 2
|
Defined in consolidated/stompjs/src/client.ts:187
|
Multiplier for adjusting tolerance when processing heartbeat signals. Tolerance level is calculated using the multiplier:
Default value is Example:
|
Public logRawCommunication |
Type : boolean
|
Defined in consolidated/stompjs/src/client.ts:558
|
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 to this setting will take effect during the next broker reconnect. Example:
|
Public maxReconnectDelay |
Type : number
|
Default value : 15 * 60 * 1000
|
Defined in consolidated/stompjs/src/client.ts:143
|
Maximum delay (in milliseconds) between reconnection attempts when using exponential backoff. Default is 15 minutes ( Example:
|
Public maxWebSocketChunkSize |
Type : number
|
Default value : 8 * 1024
|
Defined in consolidated/stompjs/src/client.ts:242
|
Maximum size (in bytes) for individual WebSocket chunks if splitLargeFrames is enabled. Default is 8 KB ( |
Public onChangeState |
Type : function
|
Defined in consolidated/stompjs/src/client.ts:646
|
Callback invoked whenever the client's state changes. This callback can be used to monitor transitions between various states, such as Example:
|
Public onConnect |
Type : frameCallbackType
|
Defined in consolidated/stompjs/src/client.ts:476
|
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. Example:
|
Public onDisconnect |
Type : frameCallbackType
|
Defined in consolidated/stompjs/src/client.ts:493
|
Callback executed upon successful disconnection from the STOMP broker. 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. Example:
|
Public onHeartbeatLost |
Type : emptyCallbackType
|
Defined in consolidated/stompjs/src/client.ts:423
|
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 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:
|
Public onHeartbeatReceived |
Type : emptyCallbackType
|
Defined in consolidated/stompjs/src/client.ts:403
|
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:
|
Public onStompError |
Type : frameCallbackType
|
Defined in consolidated/stompjs/src/client.ts:509
|
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. Example:
|
Public onUnhandledFrame | ||||
Type : frameCallbackType
|
||||
Defined in consolidated/stompjs/src/client.ts:384
|
||||
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:
|
||||
Parameters :
|
Public onUnhandledMessage | ||||
Type : messageCallbackType
|
||||
Defined in consolidated/stompjs/src/client.ts:354
|
||||
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. Usage:
|
||||
Parameters :
|
Public onUnhandledReceipt | ||||
Type : frameCallbackType
|
||||
Defined in consolidated/stompjs/src/client.ts:366
|
||||
Callback invoked when the broker sends a receipt indicating the completion of an operation. Receipts are typically requested using the Client#watchForReceipt function. Usage Example: See Client#watchForReceipt. |
||||
Parameters :
|
Public onWebSocketClose |
Type : closeEventCallbackType
|
Defined in consolidated/stompjs/src/client.ts:525
|
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, which contains details about the closure. Example:
|
Public onWebSocketError |
Type : wsErrorCallbackType
|
Defined in consolidated/stompjs/src/client.ts:540
|
Callback executed when the underlying WebSocket raises an error. This callback provides an Event representing the error raised by the WebSocket. Example:
|
Public reconnectDelay |
Type : number
|
Default value : 5000
|
Defined in consolidated/stompjs/src/client.ts:124
|
Delay (in milliseconds) between reconnection attempts if the connection drops. Set to Example:
|
Public reconnectTimeMode |
Type : ReconnectionTimeMode
|
Default value : ReconnectionTimeMode.LINEAR
|
Defined in consolidated/stompjs/src/client.ts:159
|
Mode for determining the time interval between reconnection attempts. Available modes:
Example:
|
Public splitLargeFrames |
Type : boolean
|
Default value : false
|
Defined in consolidated/stompjs/src/client.ts:235
|
Enables splitting of large text WebSocket frames into smaller chunks. This setting is enabled for brokers that support only chunked messages (e.g., Java Spring-based brokers).
Default is Warning:
Example:
|
Public state |
Type : ActivationState
|
Default value : ActivationState.INACTIVE
|
Defined in consolidated/stompjs/src/client.ts:664
|
Current activation state of the client. Possible states:
Note: The client may transition directly from |
Public stompVersions |
Default value : Versions.default
|
Defined in consolidated/stompjs/src/client.ts:68
|
STOMP protocol versions to use during the handshake. By default, the client will attempt
versions Example:
|
Public webSocketFactory |
Type : | undefined
|
Defined in consolidated/stompjs/src/client.ts:94
|
A function that returns a WebSocket or a similar object (e.g., SockJS) to establish connections. This is an alternative to Client#brokerURL. Using this allows finer control over WebSocket creation, especially for custom wrappers or when working in non-standard environments. Example:
Note:
|
Public abort | ||||||||
abort(transactionId: string)
|
||||||||
Defined in consolidated/stompjs/src/client.ts:1253
|
||||||||
Aborts a transaction. It is strongly recommended to call abort directly on the transaction object returned by client#begin. Example:
Parameters :
Returns :
void
|
Public ack | ||||||||||||||||||||
ack(messageId: string, subscriptionId: string, headers: StompHeaders)
|
||||||||||||||||||||
Defined in consolidated/stompjs/src/client.ts:1278
|
||||||||||||||||||||
Acknowledges receipt of a message. Typically, this should be done by calling ack directly on the IMessage instance passed to the subscription callback. Example:
Parameters :
Returns :
void
|
Public activate |
activate()
|
Defined in consolidated/stompjs/src/client.ts:761
|
Activates the client, initiating a connection to the STOMP broker. On activation, the client attempts to connect and sets its state to To stop reconnection attempts and disconnect, call Client#deactivate. Example:
If the client is currently
Returns :
void
|
Public begin | ||||||||
begin(transactionId?: string)
|
||||||||
Defined in consolidated/stompjs/src/client.ts:1211
|
||||||||
Starts a new transaction. The returned ITransaction object provides methods for commit and abort. If Example:
Parameters :
Returns :
ITransaction
An instance of {@link ITransaction}. |
Public commit | ||||||||
commit(transactionId: string)
|
||||||||
Defined in consolidated/stompjs/src/client.ts:1232
|
||||||||
Commits a transaction. It is strongly recommended to call commit on the transaction object returned by client#begin. Example:
Parameters :
Returns :
void
|
Public configure | ||||||||
configure(conf: StompConfig)
|
||||||||
Defined in consolidated/stompjs/src/client.ts:729
|
||||||||
Updates the client's configuration. All properties in the provided configuration object will override the current settings. Additionally, a warning is logged if Example:
Parameters :
Returns :
void
|
Public Async deactivate | ||||||||||
deactivate(options: literal type)
|
||||||||||
Defined in consolidated/stompjs/src/client.ts:976
|
||||||||||
Disconnects the client and stops the automatic reconnection loop. If there is an active STOMP connection at the time of invocation, the appropriate callbacks
will be triggered during the shutdown sequence. Once deactivated, the client will enter the
Behavior:
Experimental Option:
Example:
Parameters :
Returns :
Promise<void>
A Promise that resolves when the deactivation process completes. |
Public forceDisconnect |
forceDisconnect()
|
Defined in consolidated/stompjs/src/client.ts:1040
|
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 Note: To prevent further reconnect attempts, call Client#deactivate. Example:
Returns :
void
|
Public nack | ||||||||||||||||||||
nack(messageId: string, subscriptionId: string, headers: StompHeaders)
|
||||||||||||||||||||
Defined in consolidated/stompjs/src/client.ts:1309
|
||||||||||||||||||||
Rejects a message (negative acknowledgment). Like acknowledgments, this should typically be done by calling nack directly on the IMessage instance passed to the subscription callback. Example:
Parameters :
Returns :
void
|
Public publish | ||||||
publish(params: IPublishParams)
|
||||||
Defined in consolidated/stompjs/src/client.ts:1088
|
||||||
Sends a message to the specified destination on the STOMP broker. The Content-Length Behavior:
Notes:
Example:
Parameters :
Returns :
void
|
Public subscribe | ||||||||||||||||||||
subscribe(destination: string, callback: messageCallbackType, headers: StompHeaders)
|
||||||||||||||||||||
Defined in consolidated/stompjs/src/client.ts:1158
|
||||||||||||||||||||
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 IMessage instance. Subscription ID:
Example:
Parameters :
Returns :
StompSubscription
A {@link StompSubscription} which can be used to manage the subscription. |
Public unsubscribe | |||||||||||||||
unsubscribe(id: string, headers: StompHeaders)
|
|||||||||||||||
Defined in consolidated/stompjs/src/client.ts:1188
|
|||||||||||||||
Unsubscribes from a subscription on the STOMP broker. Prefer using the
This method can also be used directly with the subscription ID. Example:
Parameters :
Returns :
void
|
Public watchForReceipt | ||||||||||||
watchForReceipt(receiptId: string, callback: frameCallbackType)
|
||||||||||||
Defined in consolidated/stompjs/src/client.ts:1123
|
||||||||||||
Monitors for a receipt acknowledgment from the broker for specific operations. Add a The callback is invoked with the corresponding IFrame when the receipt is received. Example:
Parameters :
Returns :
void
|
webSocket |
getwebSocket()
|
Defined in consolidated/stompjs/src/client.ts:292
|
Provides access to the underlying WebSocket instance. This property is read-only. Example:
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 :
IStompSocket | undefined
|
disconnectHeaders | ||||||
getdisconnectHeaders()
|
||||||
Defined in consolidated/stompjs/src/client.ts:326
|
||||||
Allows customization of the disconnection headers. Any changes made during an active session will also be applied immediately. Example:
Returns :
StompHeaders
|
||||||
setdisconnectHeaders(value: StompHeaders)
|
||||||
Defined in consolidated/stompjs/src/client.ts:330
|
||||||
Parameters :
Returns :
void
|
connected |
getconnected()
|
Defined in consolidated/stompjs/src/client.ts:439
|
Indicates whether there is an active connection to the STOMP broker. Usage:
Returns :
boolean
|
connectedVersion |
getconnectedVersion()
|
Defined in consolidated/stompjs/src/client.ts:606
|
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:
Returns :
string | undefined
|
active |
getactive()
|
Defined in consolidated/stompjs/src/client.ts:628
|
Indicates whether the client is currently active. A client is considered active if it is connected or actively attempting to reconnect. Example:
Returns :
boolean
|
import { ITransaction } from './i-transaction.js';
import { StompConfig } from './stomp-config.js';
import { StompHandler } from './stomp-handler.js';
import { StompHeaders } from './stomp-headers.js';
import { StompSubscription } from './stomp-subscription.js';
import {
ActivationState,
closeEventCallbackType,
debugFnType,
emptyCallbackType,
frameCallbackType,
IPublishParams,
IStompSocket,
messageCallbackType,
ReconnectionTimeMode,
StompSocketState,
TickerStrategy,
wsErrorCallbackType,
} from './types.js';
import { Versions } from './versions.js';
/**
* @internal
*/
declare const WebSocket: {
prototype: IStompSocket;
new (url: string, protocols?: string | string[]): IStompSocket;
};
/**
* 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.
* 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 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
* // Configure the client to only use versions 1.1 and 1.0
* client.stompVersions = new Versions(['1.1', '1.0']);
* ```
*/
public stompVersions = Versions.default;
/**
* A function that returns a WebSocket or a similar object (e.g., SockJS) to establish connections.
*
* 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
* 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;
/**
* 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;
// 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;
/**
* 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;
/**
* 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 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* Enables splitting of large text WebSocket frames into smaller chunks.
*
* This setting is enabled for brokers that support only chunked messages (e.g., Java Spring-based brokers).
* Default is `false`.
*
* Warning:
* - Should not be used with WebSocket-compliant brokers, as chunking may cause large message failures.
* - Binary WebSocket frames are never split.
*
* Example:
* ```javascript
* client.splitLargeFrames = true;
* client.maxWebSocketChunkSize = 4096; // Allow chunks of 4 KB
* ```
*/
public splitLargeFrames: boolean = 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;
/**
* 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).
*
* Example:
* ```javascript
* client.forceBinaryWSFrames = true;
* ```
*/
public forceBinaryWSFrames: boolean = false;
/**
* Workaround for a React Native WebSocket bug, where messages containing `NULL` are chopped.
*
* Enabling this appends a `NULL` character to incoming frames to ensure they remain valid STOMP packets.
*
* Warning:
* - For brokers that split large messages, this may cause data loss or connection termination.
*
* Example:
* ```javascript
* client.appendMissingNULLonIncoming = true;
* ```
*/
public appendMissingNULLonIncoming: boolean = false;
/**
* 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 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;
/**
* 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;
}
set disconnectHeaders(value: StompHeaders) {
this._disconnectHeaders = value;
if (this._stompHandler) {
this._stompHandler.disconnectHeaders = this._disconnectHeaders;
}
}
private _disconnectHeaders: StompHeaders;
/**
* 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.
*
* Usage:
* ```javascript
* client.onUnhandledMessage = (message) => {
* console.log('Unhandled message:', message);
* };
* ```
*
* @param message The actual {@link IMessage} received.
*/
public onUnhandledMessage: messageCallbackType;
/**
* 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.
*
* Usage Example:
* See [Client#watchForReceipt]{@link Client#watchForReceipt}.
*
* @param frame The actual {@link IFrame} received from the broker.
*/
public onUnhandledReceipt: frameCallbackType;
/**
* 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);
* };
* ```
*
* @param frame The actual {@link IFrame} received from the broker.
*/
public onUnhandledFrame: frameCallbackType;
/**
* 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 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.
*
* As of version 5.1, this callback supports `async/await`, enabling seamless integration
* with asynchronous operations, such as fetching tokens or credentials.
*
* Example:
* ```javascript
* client.beforeConnect = async () => {
* const token = await fetchToken();
* client.connectHeaders = { Authorization: `Bearer ${token}` };
* };
* ```
*/
public beforeConnect: (client: Client) => void | Promise<void>;
/**
* 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.
*
* Example:
* ```javascript
* client.onConnect = (frame) => {
* console.log('Connected to broker, session ID:', frame.headers['session']);
* };
* ```
*/
public onConnect: frameCallbackType;
/**
* Callback executed upon successful disconnection from the STOMP broker.
*
* 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}.
*
* Example:
* ```javascript
* client.onDisconnect = (frame) => {
* console.log('Disconnected successfully');
* };
* ```
*/
public onDisconnect: frameCallbackType;
/**
* 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.
*
* Example:
* ```javascript
* client.onStompError = (frame) => {
* console.error('Broker reported an error:', frame.body);
* };
* ```
*/
public onStompError: frameCallbackType;
/**
* 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.
*
* Example:
* ```javascript
* client.onWebSocketClose = (event) => {
* console.log('WebSocket closed. Code:', event.code);
* };
* ```
*/
public onWebSocketClose: closeEventCallbackType;
/**
* 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.
*
* Example:
* ```javascript
* client.onWebSocketError = (event) => {
* console.error('WebSocket error:', event);
* };
* ```
*/
public onWebSocketError: wsErrorCallbackType;
/**
* 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 to this setting will take effect during the next broker reconnect.
*
* Example:
* ```javascript
* client.logRawCommunication = true; // Enable logging raw communication
* ```
*/
public logRawCommunication: boolean;
/**
* 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 = (str) => {
* console.log(str);
* };
* ```
*
* **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;
/**
* 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;
/**
* 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;
}
private _stompHandler: StompHandler | undefined;
/**
* 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;
}
/**
* 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.
*
* Example:
* ```javascript
* client.onChangeState = (state) => {
* console.log(`Client state changed to: ${state}`);
* };
* ```
*/
public onChangeState: (state: ActivationState) => void;
private _changeState(state: ActivationState) {
this.state = state;
this.onChangeState(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.
*
* Note: The client may transition directly from `ACTIVE` to `INACTIVE` without entering
* the `DEACTIVATING` state.
*/
public state: ActivationState = ActivationState.INACTIVE;
private _reconnector: any;
/**
* 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
const noOp = () => {};
this.debug = noOp;
this.beforeConnect = noOp;
this.onConnect = noOp;
this.onDisconnect = noOp;
this.onUnhandledMessage = noOp;
this.onUnhandledReceipt = noOp;
this.onUnhandledFrame = noOp;
this.onHeartbeatReceived = noOp;
this.onHeartbeatLost = noOp;
this.onStompError = noOp;
this.onWebSocketClose = noOp;
this.onWebSocketError = noOp;
this.logRawCommunication = false;
this.onChangeState = noOp;
// These parameters would typically get proper values before connect is called
this.connectHeaders = {};
this._disconnectHeaders = {};
// Apply configuration
this.configure(conf);
}
/**
* 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);
// Warn on incorrect maxReconnectDelay settings
if (
this.maxReconnectDelay > 0 &&
this.maxReconnectDelay < this.reconnectDelay
) {
this.debug(
`Warning: maxReconnectDelay (${this.maxReconnectDelay}ms) is less than reconnectDelay (${this.reconnectDelay}ms). Using reconnectDelay as the maxReconnectDelay delay.`,
);
this.maxReconnectDelay = this.reconnectDelay;
}
}
/**
* 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
* ```
*
* If the client is currently `DEACTIVATING`, connection is delayed until the deactivation process completes.
*/
public activate(): void {
const _activate = () => {
if (this.active) {
this.debug('Already ACTIVE, ignoring request to activate');
return;
}
this._changeState(ActivationState.ACTIVE);
this._nextReconnectDelay = this.reconnectDelay;
this._connect();
};
// if it is deactivating, wait for it to complete before activating.
if (this.state === ActivationState.DEACTIVATING) {
this.debug('Waiting for deactivation to finish before activating');
this.deactivate().then(() => {
_activate();
});
} else {
_activate();
}
}
private async _connect(): Promise<void> {
await this.beforeConnect(this);
if (this._stompHandler) {
this.debug(
'There is already a stompHandler, skipping the call to connect',
);
return;
}
if (!this.active) {
this.debug(
'Client has been marked inactive, will not attempt to connect',
);
return;
}
// setup connection watcher
if (this.connectionTimeout > 0) {
// clear first
if (this._connectionWatcher) {
clearTimeout(this._connectionWatcher);
}
this._connectionWatcher = setTimeout(() => {
if (this.connected) {
return;
}
// Connection not established, close the underlying socket
// a reconnection will be attempted
this.debug(
`Connection not established in ${this.connectionTimeout}ms, closing socket`,
);
this.forceDisconnect();
}, this.connectionTimeout);
}
this.debug('Opening Web Socket...');
// Get the actual WebSocket (or a similar object)
const webSocket = this._createWebSocket();
this._stompHandler = new StompHandler(this, webSocket, {
debug: this.debug,
stompVersions: this.stompVersions,
connectHeaders: this.connectHeaders,
disconnectHeaders: this._disconnectHeaders,
heartbeatIncoming: this.heartbeatIncoming,
heartbeatGracePeriods: this.heartbeatToleranceMultiplier,
heartbeatOutgoing: this.heartbeatOutgoing,
heartbeatStrategy: this.heartbeatStrategy,
splitLargeFrames: this.splitLargeFrames,
maxWebSocketChunkSize: this.maxWebSocketChunkSize,
forceBinaryWSFrames: this.forceBinaryWSFrames,
logRawCommunication: this.logRawCommunication,
appendMissingNULLonIncoming: this.appendMissingNULLonIncoming,
discardWebsocketOnCommFailure: this.discardWebsocketOnCommFailure,
onConnect: frame => {
// Successfully connected, stop the connection watcher
if (this._connectionWatcher) {
clearTimeout(this._connectionWatcher);
this._connectionWatcher = undefined;
}
if (!this.active) {
this.debug(
'STOMP got connected while deactivate was issued, will disconnect now',
);
this._disposeStompHandler();
return;
}
this.onConnect(frame);
},
onDisconnect: frame => {
this.onDisconnect(frame);
},
onStompError: frame => {
this.onStompError(frame);
},
onWebSocketClose: evt => {
this._stompHandler = undefined; // a new one will be created in case of a reconnect
if (this.state === ActivationState.DEACTIVATING) {
// Mark deactivation complete
this._changeState(ActivationState.INACTIVE);
}
// The callback is called before attempting to reconnect, this would allow the client
// to be `deactivated` in the callback.
this.onWebSocketClose(evt);
if (this.active) {
this._schedule_reconnect();
}
},
onWebSocketError: evt => {
this.onWebSocketError(evt);
},
onUnhandledMessage: message => {
this.onUnhandledMessage(message);
},
onUnhandledReceipt: frame => {
this.onUnhandledReceipt(frame);
},
onUnhandledFrame: frame => {
this.onUnhandledFrame(frame);
},
onHeartbeatReceived: () => {
this.onHeartbeatReceived();
},
onHeartbeatLost: () => {
this.onHeartbeatLost();
},
});
this._stompHandler.start();
}
private _createWebSocket(): IStompSocket {
let webSocket: IStompSocket;
if (this.webSocketFactory) {
webSocket = this.webSocketFactory();
} else if (this.brokerURL) {
webSocket = new WebSocket(
this.brokerURL,
this.stompVersions.protocolVersions(),
);
} else {
throw new Error('Either brokerURL or webSocketFactory must be provided');
}
webSocket.binaryType = 'arraybuffer';
return webSocket;
}
private _schedule_reconnect(): void {
if (this._nextReconnectDelay > 0) {
this.debug(
`STOMP: scheduling reconnection in ${this._nextReconnectDelay}ms`,
);
this._reconnector = setTimeout(() => {
if (this.reconnectTimeMode === ReconnectionTimeMode.EXPONENTIAL) {
this._nextReconnectDelay = this._nextReconnectDelay * 2;
// Truncated exponential backoff with a set limit unless disabled
if (this.maxReconnectDelay !== 0) {
this._nextReconnectDelay = Math.min(
this._nextReconnectDelay,
this.maxReconnectDelay,
);
}
}
this._connect();
}, this._nextReconnectDelay);
}
}
/**
* Disconnects the client and stops the automatic reconnection loop.
*
* If there is an active STOMP connection at the time of invocation, the appropriate callbacks
* will be triggered during the shutdown sequence. Once deactivated, the client will enter the
* `INACTIVE` state, and no further reconnection attempts will be made.
*
* **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}.
*
* **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.
*
* Example:
* ```javascript
* // Graceful disconnect
* await client.deactivate();
*
* // 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;
const needToDispose = this.active;
let retPromise: Promise<void>;
if (this.state === ActivationState.INACTIVE) {
this.debug(`Already INACTIVE, nothing more to do`);
return Promise.resolve();
}
this._changeState(ActivationState.DEACTIVATING);
// Reset reconnection timer just to be safe
this._nextReconnectDelay = 0;
// Clear if a reconnection was scheduled
if (this._reconnector) {
clearTimeout(this._reconnector);
this._reconnector = undefined;
}
if (
this._stompHandler &&
// @ts-ignore - if there is a _stompHandler, there is the webSocket
this.webSocket.readyState !== StompSocketState.CLOSED
) {
const origOnWebSocketClose = this._stompHandler.onWebSocketClose;
// we need to wait for the underlying websocket to close
retPromise = new Promise<void>((resolve, reject) => {
// @ts-ignore - there is a _stompHandler
this._stompHandler.onWebSocketClose = evt => {
origOnWebSocketClose(evt);
resolve();
};
});
} else {
// indicate that auto reconnect loop should terminate
this._changeState(ActivationState.INACTIVE);
return Promise.resolve();
}
if (force) {
this._stompHandler?.discardWebsocket();
} else if (needToDispose) {
this._disposeStompHandler();
}
return retPromise;
}
/**
* 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) {
this._stompHandler.forceDisconnect();
}
}
private _disposeStompHandler() {
// Dispose STOMP Handler
if (this._stompHandler) {
this._stompHandler.dispose();
}
}
/**
* Sends a message to the specified destination on the STOMP broker.
*
* 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 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.
*
* **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
* // 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) {
this._checkConnection();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.publish(params);
}
private _checkConnection() {
if (!this.connected) {
throw new TypeError('There is no underlying STOMP connection');
}
}
/**
* Monitors for a receipt acknowledgment from the broker for specific operations.
*
* 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 callback is invoked with the corresponding {@link IFrame} when the receipt is received.
*
* Example:
* ```javascript
* const receiptId = "unique-receipt-id";
*
* client.watchForReceipt(receiptId, (frame) => {
* console.log("Operation acknowledged by the broker:", frame);
* });
*
* // 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();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.watchForReceipt(receiptId, callback);
}
/**
* 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.
*
* **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
* const callback = (message) => {
* console.log("Received message:", message.body);
* };
*
* // Auto-generated subscription ID
* const subscription = client.subscribe("/queue/test", callback);
*
* // Explicit subscription ID
* const mySubId = "my-subscription-id";
* const subscription = client.subscribe("/queue/test", callback, { id: mySubId });
* ```
*
* @param destination Destination to subscribe to.
* @param callback Function invoked for each received message.
* @param headers Optional headers for subscription, such as `id`.
* @returns A {@link StompSubscription} which can be used to manage the subscription.
*/
public subscribe(
destination: string,
callback: messageCallbackType,
headers: StompHeaders = {},
): StompSubscription {
this._checkConnection();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
return this._stompHandler.subscribe(destination, callback, headers);
}
/**
* 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
* 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();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.unsubscribe(id, headers);
}
/**
* 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");
* ```
*
* @param transactionId Optional transaction ID.
* @returns An instance of {@link ITransaction}.
*/
public begin(transactionId?: string): ITransaction {
this._checkConnection();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
return this._stompHandler.begin(transactionId);
}
/**
* 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
* 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();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.commit(transactionId);
}
/**
* 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
* 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();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.abort(transactionId);
}
/**
* 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
* 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,
subscriptionId: string,
headers: StompHeaders = {},
): void {
this._checkConnection();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.ack(messageId, subscriptionId, headers);
}
/**
* 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
* 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,
subscriptionId: string,
headers: StompHeaders = {},
): void {
this._checkConnection();
// @ts-ignore - we already checked that there is a _stompHandler, and it is connected
this._stompHandler.nack(messageId, subscriptionId, headers);
}
}