fix: Add emitted events documentation

Closes 'update' event not always triggered #10
inwaar · Feb 25, 2023 · 78492a9 · 78492a9
1 parent a808ebe
commit 78492a9
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -86,7 +86,7 @@ Note: This command may vary depending on your OS (e.g. Linux, macOS, CygWin). If
 ## Classes
 
 <dl>
-<dt><a href="#Client">Client</a></dt>
+<dt><a href="#Client">Client</a> ⇐ <code>EventEmitter</code></dt>
 <dd><p>Control GREE HVAC device by getting and setting its properties</p>
 </dd>
 </dl>
@@ -105,21 +105,33 @@ Note: This command may vary depending on your OS (e.g. Linux, macOS, CygWin). If
 </dd>
 </dl>
 
+## Typedefs
+
+<dl>
+<dt><a href="#PropertyMap">PropertyMap</a> : <code>Object.&lt;PROPERTY, (PROPERTY_VALUE|number)&gt;</code></dt>
+<dd></dd>
+</dl>
+
 <a name="Client"></a>
 
-## Client
+## Client ⇐ <code>EventEmitter</code>
 Control GREE HVAC device by getting and setting its properties
 
 **Kind**: global class  
+**Extends**: <code>EventEmitter</code>  
+**Emits**: [<code>connect</code>](#Client+event_connect), [<code>update</code>](#Client+event_update)  
 
-* [Client](#Client)
+* [Client](#Client) ⇐ <code>EventEmitter</code>
     * [new Client(options)](#new_Client_new)
     * [.connect()](#Client+connect)
     * [.disconnect()](#Client+disconnect)
     * [.setProperties(properties)](#Client+setProperties)
     * [.setProperty(property, value)](#Client+setProperty)
     * [.getDeviceId()](#Client+getDeviceId) ⇒ <code>string</code> \| <code>null</code>
     * [.setDebug(enable)](#Client+setDebug)
+    * ["connect"](#Client+event_connect)
+    * ["success" (updated, properties)](#Client+event_success)
+    * ["update" (updated, properties)](#Client+event_update)
 
 <a name="new_Client_new"></a>
 
@@ -147,6 +159,7 @@ client.on('connect', () => {
 Connect to a HVAC device and start polling status changes by default
 
 **Kind**: instance method of [<code>Client</code>](#Client)  
+**Emits**: [<code>connect</code>](#Client+event_connect)  
 <a name="Client+disconnect"></a>
 
 ### client.disconnect()
@@ -159,10 +172,11 @@ Disconnect from a HVAC device and stop status polling
 Set a list of device properties at once by one request
 
 **Kind**: instance method of [<code>Client</code>](#Client)  
+**Emits**: [<code>success</code>](#Client+event_success)  
 
 | Param | Type |
 | --- | --- |
-| properties | <code>Object.&lt;PROPERTY, PROPERTY\_VALUE&gt;</code> | 
+| properties | [<code>PropertyMap</code>](#PropertyMap) | 
 
 **Example**  
 ```js
@@ -192,6 +206,7 @@ client.setProperties({
 Set device property
 
 **Kind**: instance method of [<code>Client</code>](#Client)  
+**Emits**: [<code>success</code>](#Client+event_success)  
 
 | Param | Type |
 | --- | --- |
@@ -229,6 +244,36 @@ Set debug level
 | --- | --- |
 | enable | <code>Boolean</code> | 
 
+<a name="Client+event_connect"></a>
+
+### "connect"
+Emitted when successfully connected to the HVAC
+
+**Kind**: event emitted by [<code>Client</code>](#Client)  
+<a name="Client+event_success"></a>
+
+### "success" (updated, properties)
+Emitted when properties successfully updated after calling setProperties or setProperty
+
+**Kind**: event emitted by [<code>Client</code>](#Client)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| updated | [<code>PropertyMap</code>](#PropertyMap) | The properties and their values that were updated |
+| properties | [<code>PropertyMap</code>](#PropertyMap) | All the properties and their values managed by the Client |
+
+<a name="Client+event_update"></a>
+
+### "update" (updated, properties)
+Emitted when properties successfully updated from HVAC (e.g. by a remote control)
+
+**Kind**: event emitted by [<code>Client</code>](#Client)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| updated | [<code>PropertyMap</code>](#PropertyMap) | The properties and their values that were updated |
+| properties | [<code>PropertyMap</code>](#PropertyMap) | All the properties and their values managed by the Client |
+
 <a name="CLIENT_OPTIONS"></a>
 
 ## CLIENT\_OPTIONS
@@ -345,6 +390,10 @@ Device properties constants
 | turbo | <code>string</code> | Sets fan speed to the maximum. Fan speed cannot be changed while active and only available in Dry and Cool mode |
 | powerSave | <code>string</code> | Power saving mode |
 
+<a name="PropertyMap"></a>
+
+## PropertyMap : <code>Object.&lt;PROPERTY, (PROPERTY\_VALUE\|number)&gt;</code>
+**Kind**: global typedef  
 
 ## License
 

diff --git a/lib/client.js b/lib/client.js
@@ -13,12 +13,39 @@ const { PropertyTransformer } = require('./property-transformer');
 
 /**
  * Control GREE HVAC device by getting and setting its properties
+ * @extends EventEmitter
  */
 class Client extends EventEmitter {
+    /**
+     * @typedef {Object.<PROPERTY, PROPERTY_VALUE|number>} PropertyMap
+     */
+
+    /**
+     * @event Client#connect
+     * @description Emitted when successfully connected to the HVAC
+     */
+
+    /**
+     * @event Client#success
+     * @param {PropertyMap} updated The properties and their values that were updated
+     * @param {PropertyMap} properties All the properties and their values managed by the Client
+     * @description Emitted when properties successfully updated after calling setProperties or setProperty
+     */
+
+    /**
+     * @event Client#update
+     * @param {PropertyMap} updated The properties and their values that were updated
+     * @param {PropertyMap} properties All the properties and their values managed by the Client
+     * @description Emitted when properties successfully updated from HVAC (e.g. by a remote control)
+     */
+
     /**
      * Creates a new client, connect to device and start polling by default.
      * @param {CLIENT_OPTIONS | {}} options
      *
+     * @fires Client#connect
+     * @fires Client#update
+     *
      * @example
      * const Gree = require('gree-hvac-client');
      *
@@ -72,7 +99,7 @@ class Client extends EventEmitter {
         /**
          * Device properties, are updated by polling the devices
          *
-         * @type {Object<string, string | number>}
+         * @type {PropertyMap}
          * @private
          */
         this._properties = {};
@@ -119,6 +146,8 @@ class Client extends EventEmitter {
 
     /**
      * Connect to a HVAC device and start polling status changes by default
+     *
+     * @fires Client#connect
      */
     connect() {
         this._socket = dgram.createSocket('udp4');
@@ -156,7 +185,8 @@ class Client extends EventEmitter {
     /**
      * Set a list of device properties at once by one request
      *
-     * @param properties {Object.<PROPERTY, PROPERTY_VALUE>}
+     * @param {PropertyMap} properties
+     * @fires Client#success
      * @example
      * // use library constants
      *
@@ -188,8 +218,9 @@ class Client extends EventEmitter {
     /**
      * Set device property
      *
-     * @param property {PROPERTY}
-     * @param value {PROPERTY_VALUE}
+     * @param {PROPERTY} property
+     * @param {PROPERTY_VALUE} value
+     * @fires Client#success
      * @example
      * // use library constants
      *
@@ -367,6 +398,7 @@ class Client extends EventEmitter {
      * Handle device binding confirmation response
      *
      * @param pack
+     * @fires Client#connect
      * @private
      */
     _handleBindingConfirmationResponse(pack) {
@@ -390,6 +422,7 @@ class Client extends EventEmitter {
      * Handle device properties status response
      *
      * @param pack
+     * @fires Client#update
      * @private
      */
     _handleStatusResponse(pack) {
@@ -418,6 +451,7 @@ class Client extends EventEmitter {
      * Handle device properties update confirmation response
      *
      * @param pack
+     * @fires Client#success
      * @private
      */
     _handleUpdateConfirmResponse(pack) {