matssocket/dist/ConnectionEvent.d.ts

MatsSocket client library

/**
 * Event object for {@link MatsSocket#addConnectionEventListener}.
 * <p />
 * <b>Note on event ordering</b>: {@link ConnectionEvent}s are delivered ASAP. This means that for events that the
 * client controls, they are issued <i/>before</i> the operation they describe commences:
 * {@link ConnectionEventType#CONNECTING CONNECTING} and
 * {@link ConnectionEventType#SESSION_ESTABLISHED SESSION_ESTABLISHED}. However, for events where the client is
 * "reacting", e.g. when the WebSocket connects, or abruptly closes, they are issued ASAP when the Client gets to know about it:
 * {@link ConnectionEventType#CONNECTED CONNECTED}, {@link ConnectionEventType#LOST_CONNECTION LOST_CONNECTION},
 * {@link ConnectionEventType#CONNECTION_ERROR CONNECTION_ERROR} and {@link ConnectionEventType#WAITING WAITING}.
 * For {@link ConnectionEventType#COUNTDOWN COUNTDOWN}, there is not much to say wrt. timing, other than you won't typically
 * get a 'countdown'-event with 0 seconds left, as that is when we transition into 'connecting' again. For events
 * that also describe {@link ConnectionState}s, the {@link MatsSocket.state} is updated before the event is fired.
 *
 * @param {ConnectionEventType} type - {@link ConnectionEvent#type}
 * @param {string} webSocketUrl - {@link ConnectionEvent#webSocketUrl}
 * @param {Event} webSocketEvent - {@link ConnectionEvent#webSocketEvent}
 * @param {number} timeoutSeconds - {@link ConnectionEvent#timeoutSeconds}
 * @param {number} countdownSeconds - {@link ConnectionEvent#countdownSeconds}
 * @param {number} connectionAttempt - {@link ConnectionEvent#connectionAttempt}
 * @class
 */
export function ConnectionEvent(type: ConnectionEventType, webSocketUrl: string, webSocketEvent: Event, timeoutSeconds: number, countdownSeconds: number, connectionAttempt: number): void;
export class ConnectionEvent {
    /**
     * Event object for {@link MatsSocket#addConnectionEventListener}.
     * <p />
     * <b>Note on event ordering</b>: {@link ConnectionEvent}s are delivered ASAP. This means that for events that the
     * client controls, they are issued <i/>before</i> the operation they describe commences:
     * {@link ConnectionEventType#CONNECTING CONNECTING} and
     * {@link ConnectionEventType#SESSION_ESTABLISHED SESSION_ESTABLISHED}. However, for events where the client is
     * "reacting", e.g. when the WebSocket connects, or abruptly closes, they are issued ASAP when the Client gets to know about it:
     * {@link ConnectionEventType#CONNECTED CONNECTED}, {@link ConnectionEventType#LOST_CONNECTION LOST_CONNECTION},
     * {@link ConnectionEventType#CONNECTION_ERROR CONNECTION_ERROR} and {@link ConnectionEventType#WAITING WAITING}.
     * For {@link ConnectionEventType#COUNTDOWN COUNTDOWN}, there is not much to say wrt. timing, other than you won't typically
     * get a 'countdown'-event with 0 seconds left, as that is when we transition into 'connecting' again. For events
     * that also describe {@link ConnectionState}s, the {@link MatsSocket.state} is updated before the event is fired.
     *
     * @param {ConnectionEventType} type - {@link ConnectionEvent#type}
     * @param {string} webSocketUrl - {@link ConnectionEvent#webSocketUrl}
     * @param {Event} webSocketEvent - {@link ConnectionEvent#webSocketEvent}
     * @param {number} timeoutSeconds - {@link ConnectionEvent#timeoutSeconds}
     * @param {number} countdownSeconds - {@link ConnectionEvent#countdownSeconds}
     * @param {number} connectionAttempt - {@link ConnectionEvent#connectionAttempt}
     * @class
     */
    constructor(type: ConnectionEventType, webSocketUrl: string, webSocketEvent: Event, timeoutSeconds: number, countdownSeconds: number, connectionAttempt: number);
    /**
     * The type of the <code>ConnectionEvent</code>, returns an enum value of {@link ConnectionEventType}.
     *
     * @type {ConnectionEventType}
     */
    type: ConnectionEventType;
    /**
     * Holds the current URL we're either connected to, was connected to, or trying to connect to.
     *
     * @type {string}
     */
    webSocketUrl: string;
    /**
     * For several of the events (enumerated in {@link ConnectionEventType}), there is an underlying WebSocket event
     * that caused it. This field holds that.
     * <ul>
     *     <li>{@link ConnectionEventType#WAITING}: WebSocket {@link CloseEvent} that caused this transition.</li>
     *     <li>{@link ConnectionEventType#CONNECTED}: WebSocket {@link Event} that caused this transition.</li>
     *     <li>{@link ConnectionEventType#CONNECTION_ERROR}: WebSocket {@link Event} that caused this transition.</li>
     *     <li>{@link ConnectionEventType#LOST_CONNECTION}: WebSocket {@link CloseEvent} that caused it.</li>
     * </ul>
     *
     * @type {Event}
     */
    webSocketEvent: Event;
    /**
     * For {@link ConnectionEventType#CONNECTING}, {@link ConnectionEventType#WAITING} and {@link ConnectionEventType#COUNTDOWN},
     * tells how long the timeout for this attempt is, i.e. what the COUNTDOWN events start out with. Together with
     * {@link #countdownSeconds} of the COUNTDOWN events, this can be used to calculate a fraction if you want to
     * make a "progress bar" of sorts.
     * <p/>
     * The timeouts starts at 500 ms (unless there is only 1 URL configured, in which case 5 seconds), and then
     * increases exponentially, but maxes out at 15 seconds.
     *
     * @type {number}
     */
    timeoutSeconds: number;
    /**
     * For {@link ConnectionEventType#CONNECTING}, {@link ConnectionEventType#WAITING} and {@link ConnectionEventType#COUNTDOWN},
     * tells how many seconds there are left for this attempt (of the {@link #timeoutSeconds} it started with),
     * with a tenth of a second as precision. With the COUNTDOWN events, these come in each 100 ms (1/10 second),
     * and show how long time there is left before trying again (if MatsSocket is configured with multiple URLs,
     * the next attempt will be a different URL).
     * <p/>
     * The countdown is started when the state transitions to {@link ConnectionEventType#CONNECTING}, and
     * stops either when {@link ConnectionEventType#CONNECTED} or the timeout reaches zero. If the
     * state is still CONNECTING when the countdown reaches zero, implying that the "new WebSocket(..)" call still
     * has not either opened or closed, the connection attempt is aborted by calling webSocket.close(). It then
     * tries again, possibly with a different URL - and the countdown starts over.
     * <p/>
     * Notice that the countdown is not affected by any state transition into {@link ConnectionEventType#WAITING} -
     * such transition only means that the "new WebSocket(..)" call failed and emitted a close-event, but we will
     * still wait out the countdown before trying again.
     * <p/>
     * Notice that you will most probably not get an event with 0 seconds, as that is when we transition into
     * {@link ConnectionEventType#CONNECTING} and the countdown starts over (possibly with a larger timeout).
     * <p/>
     * Truncated exponential backoff: The timeouts starts at 500 ms (unless there is only 1 URL configured, in which
     * case 5 seconds), and then increases exponentially, but maxes out at 15 seconds.
     *
     * @type {number}
     */
    countdownSeconds: number;
    /**
     * The connection attempt count, starts at 0th attempt and increases for each time the connection attempt fails.
     *
     * @type {number}
     */
    connectionAttempt: number;
}
/**
 * *
 */
export type ConnectionEventType = string;
export namespace ConnectionEventType {
    let CONNECTING: string;
    let WAITING: string;
    let CONNECTED: string;
    let SESSION_ESTABLISHED: string;
    let CONNECTION_ERROR: string;
    let LOST_CONNECTION: string;
    let COUNTDOWN: string;
}
//# sourceMappingURL=ConnectionEvent.d.ts.map