@stomp/stompjs 6.1.2 → 7.0.0-beta1

package/src/client.ts

@@ -40,7 +40,7 @@ export class Client {
    * 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}.
    */
-  public brokerURL: string;
+  public brokerURL: string | undefined;
 
   /**
    * STOMP versions to attempt during STOMP handshake. By default versions `1.0`, `1.1`, and `1.2` are attempted.
@@ -74,7 +74,7 @@ export class Client {
    *        };
    * ```
    */
-  public webSocketFactory: () => IStompSocket;
+  public webSocketFactory: (() => IStompSocket) | undefined;
 
   /**
    * Will retry if Stomp connection is not established in specified milliseconds.
@@ -82,7 +82,8 @@ export class Client {
    */
   public connectionTimeout: number = 0;
 
-  private _connectionWatcher: number; // Timer
+  // As per https://stackoverflow.com/questions/45802988/typescript-use-correct-version-of-settimeout-node-vs-window/56239226#56239226
+  private _connectionWatcher: ReturnType<typeof setTimeout> | undefined; // Timer
 
   /**
    *  automatically reconnect with delay in milliseconds, set to 0 to disable.
@@ -145,8 +146,8 @@ export class Client {
   /**
    * Underlying WebSocket instance, READONLY.
    */
-  get webSocket(): IStompSocket {
-    return this._stompHandler ? this._stompHandler._webSocket : undefined;
+  get webSocket(): IStompSocket | undefined {
+    return this._stompHandler?._webSocket;
   }
 
   /**
@@ -298,16 +299,16 @@ export class Client {
    * In case of incoming heartbeat failure, this experimental flag instructs the library
    * to discard the socket immediately (even before it is actually closed).
    */
-  public discardWebsocketOnCommFailure: boolean;
+  public discardWebsocketOnCommFailure: boolean = false;
 
   /**
    * version of STOMP protocol negotiated with the server, READONLY
    */
-  get connectedVersion(): string {
+  get connectedVersion(): string | undefined {
     return this._stompHandler ? this._stompHandler.connectedVersion : undefined;
   }
 
-  private _stompHandler: StompHandler;
+  private _stompHandler: StompHandler | undefined;
 
   /**
    * if the client is active (connected or going to reconnect)
@@ -328,9 +329,6 @@ export class Client {
     this.onChangeState(state);
   }
 
-  // This will mark deactivate to complete, to be called after Websocket is closed
-  private _resolveSocketClose: (value?: PromiseLike<void> | void) => void;
-
   /**
    * Activation state.
    *
@@ -481,14 +479,13 @@ export class Client {
 
         if (this.state === ActivationState.DEACTIVATING) {
           // Mark deactivation complete
-          this._resolveSocketClose();
-          this._resolveSocketClose = undefined;
           this._changeState(ActivationState.INACTIVE);
         }
 
-        this.onWebSocketClose(evt);
         // 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();
         }
@@ -515,11 +512,13 @@ export class Client {
 
     if (this.webSocketFactory) {
       webSocket = this.webSocketFactory();
-    } else {
+    } 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;
@@ -537,20 +536,33 @@ export class Client {
 
   /**
    * Disconnect if connected and stop auto reconnect loop.
-   * Appropriate callbacks will be invoked if underlying STOMP connection was connected.
+   * Appropriate callbacks will be invoked if there is an underlying STOMP connection.
+   *
+   * 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.
+   *
+   * It is not an error to invoke this method more than once.
+   * Each of those would resolve on completion of deactivation.
    *
-   * This call is async, it will resolve immediately if there is no underlying active websocket,
-   * otherwise, it will resolve after underlying websocket is properly disposed.
+   * To reactivate, you can call [Client#activate]{@link Client#activate}.
    *
-   * To reactivate you can call [Client#activate]{@link Client#activate}.
+   * 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.
+   *
+   * It is possible to invoke this method initially without the `force` option
+   * and subsequently, say after a wait, with the `force` option.
    */
-  public async deactivate(): Promise<void> {
+  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.ACTIVE) {
-      this.debug(
-        `Already ${ActivationState[this.state]}, ignoring call to deactivate`
-      );
+    if (this.state === ActivationState.INACTIVE) {
+      this.debug(`Already INACTIVE, nothing more to do`);
       return Promise.resolve();
     }
 
@@ -559,15 +571,22 @@ export class Client {
     // 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
     ) {
-      // we need to wait for underlying websocket to close
+      const origOnWebSocketClose = this._stompHandler.onWebSocketClose;
+      // we need to wait for the underlying websocket to close
       retPromise = new Promise<void>((resolve, reject) => {
-        this._resolveSocketClose = resolve;
+        // @ts-ignore - there is a _stompHandler
+        this._stompHandler.onWebSocketClose = evt => {
+          origOnWebSocketClose(evt);
+          resolve();
+        };
       });
     } else {
       // indicate that auto reconnect loop should terminate
@@ -575,7 +594,11 @@ export class Client {
       return Promise.resolve();
     }
 
-    this._disposeStompHandler();
+    if (force) {
+      this._stompHandler?.discardWebsocket();
+    } else if (needToDispose) {
+      this._disposeStompHandler();
+    }
 
     return retPromise;
   }
@@ -596,7 +619,6 @@ export class Client {
     // Dispose STOMP Handler
     if (this._stompHandler) {
       this._stompHandler.dispose();
-      this._stompHandler = null;
     }
   }
 
@@ -637,9 +659,17 @@ export class Client {
    * ```
    */
   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');
+    }
+  }
+
   /**
    * 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.
@@ -676,6 +706,8 @@ export class Client {
    * ```
    */
   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);
   }
 
@@ -708,6 +740,8 @@ export class Client {
     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);
   }
 
@@ -724,6 +758,8 @@ export class Client {
    * See: http://stomp.github.com/stomp-specification-1.2.html#UNSUBSCRIBE 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);
   }
 
@@ -734,6 +770,8 @@ export class Client {
    * `transactionId` is optional, if not passed the library will generate it internally.
    */
   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);
   }
 
@@ -750,6 +788,8 @@ export class Client {
    * ```
    */
   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);
   }
 
@@ -765,6 +805,8 @@ export class Client {
    * ```
    */
   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);
   }
 
@@ -786,6 +828,8 @@ export class Client {
     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);
   }
 
@@ -807,6 +851,8 @@ export class Client {
     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);
   }
 }

package/src/frame-impl.ts

@@ -31,9 +31,9 @@ export class FrameImpl implements IFrame {
     if (!this._body && this.isBinaryBody) {
       this._body = new TextDecoder().decode(this._binaryBody);
     }
-    return this._body;
+    return this._body || '';
   }
-  private _body: string;
+  private _body: string | undefined;
 
   /**
    * body as Uint8Array
@@ -42,9 +42,10 @@ export class FrameImpl implements IFrame {
     if (!this._binaryBody && !this.isBinaryBody) {
       this._binaryBody = new TextEncoder().encode(this._body);
     }
-    return this._binaryBody;
+    // At this stage it will definitely have a valid value
+    return this._binaryBody as Uint8Array;
   }
-  private _binaryBody: Uint8Array;
+  private _binaryBody: Uint8Array | undefined;
 
   private escapeHeaderValues: boolean;
   private skipContentLengthHeader: boolean;
@@ -115,7 +116,7 @@ export class FrameImpl implements IFrame {
     }
 
     return new FrameImpl({
-      command: rawFrame.command,
+      command: rawFrame.command as string,
       headers,
       binaryBody: rawFrame.binaryBody,
       escapeHeaderValues,
@@ -140,7 +141,10 @@ export class FrameImpl implements IFrame {
     const cmdAndHeaders = this.serializeCmdAndHeaders();
 
     if (this.isBinaryBody) {
-      return FrameImpl.toUnit8Array(cmdAndHeaders, this._binaryBody).buffer;
+      return FrameImpl.toUnit8Array(
+        cmdAndHeaders,
+        this._binaryBody as Uint8Array
+      ).buffer;
     } else {
       return cmdAndHeaders + this._body + BYTE.NULL;
     }

package/src/parser.ts

@@ -63,12 +63,14 @@ export class Parser {
   private readonly _encoder = new TextEncoder();
   private readonly _decoder = new TextDecoder();
 
+  // @ts-ignore - it always has a value
   private _results: IRawFrameType;
 
   private _token: number[] = [];
-  private _headerKey: string;
-  private _bodyBytesRemaining: number;
+  private _headerKey: string | undefined;
+  private _bodyBytesRemaining: number | undefined;
 
+  // @ts-ignore - it always has a value
   private _onByte: (byte: number) => void;
 
   public constructor(
@@ -176,7 +178,10 @@ export class Parser {
       return;
     }
     if (byte === LF) {
-      this._results.headers.push([this._headerKey, this._consumeTokenAsUTF8()]);
+      this._results.headers.push([
+        this._headerKey as string,
+        this._consumeTokenAsUTF8(),
+      ]);
       this._headerKey = undefined;
       this._onByte = this._collectHeaders;
       return;
@@ -209,7 +214,7 @@ export class Parser {
 
   private _collectBodyFixedSize(byte: number): void {
     // It is post decrement, so that we discard the trailing NULL octet
-    if (this._bodyBytesRemaining-- === 0) {
+    if ((this._bodyBytesRemaining as number)-- === 0) {
       this._retrievedBody();
       return;
     }
@@ -219,7 +224,14 @@ export class Parser {
   private _retrievedBody() {
     this._results.binaryBody = this._consumeTokenAsRaw();
 
-    this.onFrame(this._results);
+    try {
+      this.onFrame(this._results);
+    } catch (e) {
+      console.log(
+        `Ignoring an exception thrown by a frame handler. Original exception: `,
+        e
+      );
+    }
 
     this._initState();
   }

package/src/stomp-handler.ts

@@ -4,7 +4,6 @@ import { FrameImpl } from './frame-impl';
 import { IMessage } from './i-message';
 import { ITransaction } from './i-transaction';
 import { Parser } from './parser';
-import { StompConfig } from './stomp-config';
 import { StompHeaders } from './stomp-headers';
 import { StompSubscription } from './stomp-subscription';
 import {
@@ -14,6 +13,7 @@ import {
   IPublishParams,
   IStompSocket,
   IStompSocketMessageEvent,
+  IStomptHandlerConfig,
   messageCallbackType,
   StompSocketState,
   wsErrorCallbackType,
@@ -69,16 +69,16 @@ export class StompHandler {
 
   public discardWebsocketOnCommFailure: boolean;
 
-  get connectedVersion(): string {
+  get connectedVersion(): string | undefined {
     return this._connectedVersion;
   }
-  private _connectedVersion: string;
+  private _connectedVersion: string | undefined;
 
   get connected(): boolean {
     return this._connected;
   }
 
-  private _connected: boolean;
+  private _connected: boolean = false;
 
   private readonly _subscriptions: { [key: string]: messageCallbackType };
   private readonly _receiptWatchers: { [key: string]: frameCallbackType };
@@ -89,12 +89,10 @@ export class StompHandler {
   private _ponger: any;
   private _lastServerActivityTS: number;
 
-  private _onclose: (closeEvent: any) => void;
-
   constructor(
     private _client: Client,
     public _webSocket: IStompSocket,
-    config: StompConfig = {}
+    config: IStomptHandlerConfig
   ) {
     // used to index subscribers
     this._counter = 0;
@@ -111,12 +109,26 @@ export class StompHandler {
 
     this._lastServerActivityTS = Date.now();
 
-    this.configure(config);
-  }
-
-  public configure(conf: StompConfig): void {
-    // bulk assign all properties to this
-    (Object as any).assign(this, conf);
+    this.debug = config.debug;
+    this.stompVersions = config.stompVersions;
+    this.connectHeaders = config.connectHeaders;
+    this.disconnectHeaders = config.disconnectHeaders;
+    this.heartbeatIncoming = config.heartbeatIncoming;
+    this.heartbeatOutgoing = config.heartbeatOutgoing;
+    this.splitLargeFrames = config.splitLargeFrames;
+    this.maxWebSocketChunkSize = config.maxWebSocketChunkSize;
+    this.forceBinaryWSFrames = config.forceBinaryWSFrames;
+    this.logRawCommunication = config.logRawCommunication;
+    this.appendMissingNULLonIncoming = config.appendMissingNULLonIncoming;
+    this.discardWebsocketOnCommFailure = config.discardWebsocketOnCommFailure;
+    this.onConnect = config.onConnect;
+    this.onDisconnect = config.onDisconnect;
+    this.onStompError = config.onStompError;
+    this.onWebSocketClose = config.onWebSocketClose;
+    this.onWebSocketError = config.onWebSocketError;
+    this.onUnhandledMessage = config.onUnhandledMessage;
+    this.onUnhandledReceipt = config.onUnhandledReceipt;
+    this.onUnhandledFrame = config.onUnhandledFrame;
   }
 
   public start(): void {
@@ -155,17 +167,18 @@ export class StompHandler {
         this.debug(`<<< ${rawChunkAsString}`);
       }
 
-      parser.parseChunk(evt.data, this.appendMissingNULLonIncoming);
+      parser.parseChunk(
+        evt.data as string | ArrayBuffer,
+        this.appendMissingNULLonIncoming
+      );
     };
 
-    this._onclose = (closeEvent): void => {
+    this._webSocket.onclose = (closeEvent): void => {
       this.debug(`Connection closed to ${this._client.brokerURL}`);
       this._cleanUp();
       this.onWebSocketClose(closeEvent);
     };
 
-    this._webSocket.onclose = this._onclose;
-
     this._webSocket.onerror = (errorEvent): void => {
       this.onWebSocketError(errorEvent);
     };
@@ -303,7 +316,7 @@ export class StompHandler {
       this.debug(
         'Discarding websocket, the underlying socket may linger for a while'
       );
-      this._discardWebsocket();
+      this.discardWebsocket();
     } else {
       this.debug('Issuing close on the websocket');
       this._closeWebsocket();
@@ -326,11 +339,12 @@ export class StompHandler {
     this._webSocket.close();
   }
 
-  private _discardWebsocket() {
-    if (!this._webSocket.terminate) {
+  public discardWebsocket() {
+    if (typeof this._webSocket.terminate !== 'function') {
       augmentWebsocket(this._webSocket, (msg: string) => this.debug(msg));
     }
 
+    // @ts-ignore - this method will be there at this stage
     this._webSocket.terminate();
   }
 
@@ -413,9 +427,11 @@ export class StompHandler {
 
     if (this._pinger) {
       clearInterval(this._pinger);
+      this._pinger = undefined;
     }
     if (this._ponger) {
       clearInterval(this._ponger);
+      this._ponger = undefined;
     }
   }
 

package/src/stomp-subscription.ts

@@ -5,14 +5,14 @@ import { StompHeaders } from './stomp-headers';
  *
  * Part of `@stomp/stompjs`.
  */
-export class StompSubscription {
+export interface StompSubscription {
   /**
    * Id associated with this subscription.
    */
-  public id: string;
+  id: string;
 
   /**
    * Unsubscribe. See [Client#unsubscribe]{@link Client#unsubscribe} for an example.
    */
-  public unsubscribe: (headers?: StompHeaders) => void;
+  unsubscribe: (headers?: StompHeaders) => void;
 }

package/src/types.ts

@@ -1,6 +1,7 @@
 import { IFrame } from './i-frame';
 import { IMessage } from './i-message';
 import { StompHeaders } from './stomp-headers';
+import { Versions } from './versions';
 
 /**
  * This callback will receive a `string` as parameter.
@@ -91,9 +92,9 @@ export type RawHeaderType = [string, string];
  * @internal
  */
 export interface IRawFrameType {
-  command: string;
+  command: string | undefined;
   headers: RawHeaderType[];
-  binaryBody: Uint8Array;
+  binaryBody: Uint8Array | undefined;
 }
 
 /**
@@ -154,3 +155,29 @@ export enum ActivationState {
   DEACTIVATING,
   INACTIVE,
 }
+
+/**
+ * @internal
+ */
+export interface IStomptHandlerConfig {
+  debug: debugFnType;
+  stompVersions: Versions;
+  connectHeaders: StompHeaders;
+  disconnectHeaders: StompHeaders;
+  heartbeatIncoming: number;
+  heartbeatOutgoing: number;
+  splitLargeFrames: boolean;
+  maxWebSocketChunkSize: number;
+  forceBinaryWSFrames: boolean;
+  logRawCommunication: boolean;
+  appendMissingNULLonIncoming: boolean;
+  discardWebsocketOnCommFailure: boolean;
+  onConnect: frameCallbackType;
+  onDisconnect: frameCallbackType;
+  onStompError: frameCallbackType;
+  onWebSocketClose: closeEventCallbackType;
+  onWebSocketError: wsErrorCallbackType;
+  onUnhandledMessage: messageCallbackType;
+  onUnhandledReceipt: frameCallbackType;
+  onUnhandledFrame: frameCallbackType;
+}

package/src/versions.ts

@@ -21,9 +21,9 @@ export class Versions {
    * @internal
    */
   public static default = new Versions([
-    Versions.V1_0,
-    Versions.V1_1,
     Versions.V1_2,
+    Versions.V1_1,
+    Versions.V1_0,
   ]);
 
   /**