Rework types

Author: mpetazzoni

lib/sse.js

@@ -18,6 +18,124 @@
  * limitations under the License.
  */
 
+/**
+ * @typedef { {[key: string]: string} } SSEHeaders
+ */
+
+/**
+ * @typedef {Object} SSEOptions
+ * @property {SSEHeaders} [headers] - headers
+ * @property {string} [payload] - payload as a string
+ * @property {string} [method] - HTTP Method
+ * @property {boolean} [withCredentials] - flag, if credentials needed
+ * @property {boolean} [start] - flag, if streaming should start automatically
+ * @property {boolean} [debug] - debugging flag
+ */
+
+/**
+ * @typedef {Object} _SSEvent
+ * @property {string} id
+ * @property {string} data
+ */
+
+/**
+ * @typedef {Object} _ReadyStateEvent
+ * @property {number} readyState
+ */
+
+/**
+ * @typedef {Object} _ErrorEVent
+ * @property {number} responseCode
+ * @property {string} data
+ */
+
+/**
+ * @typedef {Event & _SSEvent} SSEvent
+ */
+
+/**
+ * @typedef {SSEvent & _ReadyStateEvent} ReadyStateEvent
+ */
+
+/**
+ * @typedef {SSEvent & _ErrorEVent} ErrorEvent
+ */
+
+/**
+ * @callback Stream
+ * @returns {void}
+ */
+
+/**
+ * @callback Close
+ * @returns {void}
+ */
+
+/**
+ * @callback OnMessage
+ * @param {SSEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @callback OnOpen
+ * @param {SSEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @callback OnLoad
+ * @param {SSEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @callback OnReadyStateChange
+ * @param {ReadyStateEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @callback OnError
+ * @param {ErrorEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @callback OnAbort
+ * @param {SSEvent} event
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Object} SSE
+ * @property {SSEHeaders} headers - headers
+ * @property {string} payload - Payload to send in the XHR request
+ * @property {string} method - HTTP Method
+ * @property {boolean} withCredentials - flag, if credentials needed
+ * @property {boolean} debug - debugging flag
+ * @property {string} FIELD_SEPARATOR
+ * @property {Record<string, Function[]>} listeners
+ * @property {XMLHttpRequest | null} xhr
+ * @property {number} readyState
+ * @property {number} progress
+ * @property {string} chunk
+ * @property {-1} INITIALIZING
+ * @property {0} CONNECTING
+ * @property {1} OPEN
+ * @property {2} CLOSED
+ * @property {AddEventListener} addEventListener
+ * @property {RemoveEventListener} removeEventListener
+ * @property {DispatchEvent} dispatchEvent
+ * @property {Stream} stream
+ * @property {Close} close
+ * @property {OnMessage} onmessage
+ * @property {OnOpen} onopen
+ * @property {OnLoad} onload
+ * @property {OnReadyStateChange} onreadystatechange
+ * @property {OnError} onerror
+ * @property {OnAbort} onabort
+ */
 
 /**
  * @type SSE
@@ -58,7 +176,9 @@ var SSE = function (url, options) {
   this.lastEventId = '';
 
   /**
-   * @type AddEventListener
+   * @param {string} type
+   * @param {EventListener} listener
+   * @returns {void}
    */
   this.addEventListener = function(type, listener) {
     if (this.listeners[type] === undefined) {
@@ -71,7 +191,9 @@ var SSE = function (url, options) {
   };
 
   /**
-   * @type RemoveEventListener
+   * @param {string} type
+   * @param {EventListener} listener
+   * @returns {void}
    */
   this.removeEventListener = function(type, listener) {
     if (this.listeners[type] === undefined) {
@@ -92,7 +214,8 @@ var SSE = function (url, options) {
   };
 
   /**
-   * @type DispatchEvent
+   * @param {Event} e
+   * @returns {boolean}
    */
   this.dispatchEvent = function(e) {
     if (!e) {
@@ -137,6 +260,7 @@ var SSE = function (url, options) {
     this.dispatchEvent(event);
   };
 
+  /** @private */
   this._onStreamFailure = function(e) {
     const event = new CustomEvent('error');
     event.responseCode = e.currentTarget.status;
@@ -145,6 +269,7 @@ var SSE = function (url, options) {
     this._markClosed();
   }
 
+  /** @private */
   this._onStreamAbort = function() {
     this.dispatchEvent(new CustomEvent('abort'));
     this._markClosed();
@@ -191,6 +316,8 @@ var SSE = function (url, options) {
   };
 
   /**
+   * @private
+   *
    * Parse a received SSE event chunk into a constructed event object.
    *
    * Reference: https://html.spec.whatwg.org/multipage/server-sent-events.html#dispatchMessage
@@ -245,6 +372,7 @@ var SSE = function (url, options) {
     return event;
   };
 
+  /** @private */
   this._onReadyStateChange = function() {
     if (!this.xhr) {
       return;
@@ -270,9 +398,9 @@ var SSE = function (url, options) {
   };
 
   /**
-   * starts the streaming
-   * @type Stream
-   * @return {void}
+   * Starts the streaming; only needed if the start option was set to false.
+   *
+   * @type {Stream}
    */
   this.stream = function() {
     if (this.xhr) {
@@ -300,9 +428,9 @@ var SSE = function (url, options) {
   };
 
   /**
-   * closes the stream
-   * @type Close
-   * @return {void}
+   * Closes the stream
+   *
+   * @type {Close}
    */
   this.close = function() {
     if (this.readyState === SSE.CLOSED) {
@@ -333,117 +461,4 @@ if (typeof exports !== 'undefined') {
 }
 
 // Export as an ECMAScript module
-export { SSE };
-
-/**
- * @typedef { {[key: string]: string} } SSEHeaders
- */
-/**
- * @typedef {Object} SSEOptions
- * @property {SSEHeaders} [headers] - headers
- * @property {string} [payload] - payload as a string
- * @property {string} [method] - HTTP Method
- * @property {boolean} [withCredentials] - flag, if credentials needed
- * @property {boolean} [start] - flag, if streaming should start automatically
- * @property {boolean} [debug] - debugging flag
- */
-/**
- * @typedef {Object} _SSEvent
- * @property {string} id
- * @property {string} data
- */
-/**
- * @typedef {Object} _ReadyStateEvent
- * @property {number} readyState
- */
-/**
- * @typedef {Event & _SSEvent} SSEvent
- */
-/**
- * @typedef {SSEvent & _ReadyStateEvent} ReadyStateEvent
- */
-/**
- * @callback AddEventListener
- * @param {string} type
- * @param {function} listener
- * @returns {void}
- */
-/**
- * @callback RemoveEventListener
- * @param {string} type
- * @param {function} listener
- * @returns {void}
- */
-/**
- * @callback DispatchEvent
- * @param {string} type
- * @param {function} listener
- * @returns {boolean}
- */
-/**
- * @callback Stream
- * @returns {void}
- */
-/**
- * @callback Close
- * @returns {void}
- */
-/**
- * @callback OnMessage
- * @param {SSEvent} event
- * @returns {void}
- */
-/**
- * @callback OnOpen
- * @param {SSEvent} event
- * @returns {void}
- */
-/**
- * @callback OnLoad
- * @param {SSEvent} event
- * @returns {void}
- */
-/**
- * @callback OnReadystatechange
- * @param {ReadyStateEvent} event
- * @returns {void}
- */
-/**
- * @callback OnError
- * @param {SSEvent} event
- * @returns {void}
- */
-/**
- * @callback OnAbort
- * @param {SSEvent} event
- * @returns {void}
- */
-/**
- * @typedef {Object} SSE
- * @property {SSEHeaders} headers - headers
- * @property {string} payload - payload as a string
- * @property {string} method - HTTP Method
- * @property {boolean} withCredentials - flag, if credentials needed
- * @property {boolean} debug - debugging flag
- * @property {string} FIELD_SEPARATOR
- * @property {Record<string, Function[]>} listeners
- * @property {XMLHttpRequest | null} xhr
- * @property {number} readyState
- * @property {number} progress
- * @property {string} chunk
- * @property {-1} INITIALIZING
- * @property {0} CONNECTING
- * @property {1} OPEN
- * @property {2} CLOSED
- * @property {AddEventListener} addEventListener
- * @property {RemoveEventListener} removeEventListener
- * @property {DispatchEvent} dispatchEvent
- * @property {Stream} stream
- * @property {Close} close
- * @property {OnMessage} onmessage
- * @property {OnOpen} onopen
- * @property {OnLoad} onload
- * @property {OnReadystatechange} onreadystatechange
- * @property {OnError} onerror
- * @property {OnAbort} onabort
- */
+export { SSE };