[items] Item: Add increaseValueTo/decreaseValueTo methods (#371)

Closes #369. Also: - Make `Item::getToggleState` method private. - Adjust `Item::getToggleState`/`Item::sendToggleCommand` method to `Item.type` changes from a previous PR - Use brightness value of Color Items for `Item::numericState`. --------- Signed-off-by: Florian Hotze <[email protected]>
openhab · Sep 18, 2024 · 2348409 · 2348409
1 parent a16729f
commit 2348409
Show file tree

Hide file tree

Showing 14 changed files with 116 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -406,6 +406,9 @@ Calling `getItem(...)` or `...` returns an `Item` object with the following prop
   - .removeMetadata(namespace) ⇒ `object|null`
   - .sendCommand(value): `value` can be a string, a [`time.ZonedDateTime`](#time) or a [`Quantity`](#quantity)
   - .sendCommandIfDifferent(value) ⇒ `boolean`: `value` can be a string, a [`time.ZonedDateTime`](#time) or a [`Quantity`](#quantity)
+  - .sendIncreaseCommand(value) ⇒ `boolean`: `value` can be a number, or a [`Quantity`](#quantity)
+  - .sendDecreaseCommand(value) ⇒ `boolean`: `value` can be a number, or a [`Quantity`](#quantity)
+  - .sendToggleCommand(): Sends a command to flip the Item's state (e.g. if it is 'ON' an 'OFF' command is sent).
   - .postUpdate(value): `value` can be a string, a [`time.ZonedDateTime`](#time) or a [`Quantity`](#quantity)
   - .addGroups(...groupNamesOrItems)
   - .removeGroups(...groupNamesOrItems)

diff --git a/src/items/items.js b/src/items/items.js
@@ -10,7 +10,7 @@ const log = require('../log')('items');
 const { _toOpenhabPrimitiveType, _isQuantity, _isItem } = require('../helpers');
 const { getQuantity, QuantityError } = require('../quantity');
 
-const { UnDefType, OnOffType, events, itemRegistry } = require('@runtime');
+const { OnOffType, PercentType, UnDefType, events, itemRegistry } = require('@runtime');
 
 const metadata = require('./metadata/metadata');
 const ItemPersistence = require('./item-persistence');
@@ -124,7 +124,9 @@ class Item {
    * @type {number|null}
    */
   get numericState () {
-    const numericState = parseFloat(this.rawState.toString());
+    let state = this.rawState.toString();
+    if (this.type === 'Color') state = this.rawItem.getStateAs(PercentType).toString();
+    const numericState = parseFloat(state);
     return isNaN(numericState) ? null : numericState;
   }
 
@@ -247,7 +249,7 @@ class Item {
   sendCommandIfDifferent (value) {
     // value and current state both are Quantity and have equal value
     if (_isQuantity(value) && this.quantityState !== null) {
-      if (this.quantityState.equal(value)) {
+      if (value.equal(this.quantityState)) {
         return false;
       }
     }
@@ -271,20 +273,79 @@ class Item {
   }
 
   /**
-   * Calculates the toggled state of this Item. For Items like Color and
-   * Dimmer, getStateAs(OnOffType) is used and the toggle calculated off
-   * of that.
+   * Increase the value of this Item to the given value by sending a command, but only if the current state is less than that value.
+   *
+   * @param {number|Quantity|HostState} value the value of the command to send, such as 'ON'
+   * @return {boolean} true if the command was sent, false otherwise
+   */
+  sendIncreaseCommand (value) {
+    // value and current state both are Quantity and value is less than or equal current state
+    if (_isQuantity(value) && this.quantityState !== null) {
+      if (value.lessThanOrEqual(this.quantityState)) {
+        log.debug('sendIncreaseCommand: Ignoring command {} for Item {} with state {}', value, this.name, this.state);
+        return false;
+      }
+    }
+
+    // value and current state are both numeric and value is less than or equal current state
+    if (typeof value === 'number' && this.numericState !== null) {
+      if (value <= this.numericState) {
+        log.debug('sendIncreaseCommand: Ignoring command {} for Item {} with state {}', value, this.name, this.state);
+        return false;
+      }
+    }
+
+    // else send the command
+    log.debug('sendIncreaseCommand: Sending command {} to Item {} with state {}', value, this.name, this.state);
+    this.sendCommand(value);
+    return true;
+  }
+
+  /**
+   * Decreases the value of this Item to the given value by sending a command, but only if the current state is greater than that value.
+   *
+   * @param {number|Quantity|HostState} value the value of the command to send, such as 'ON'
+   * @return {boolean} true if the command was sent, false otherwise
+   */
+  sendDecreaseCommand (value) {
+    // value and current state both are Quantity and value is greater than or equal current state
+    if (_isQuantity(value) && this.quantityState !== null) {
+      if (value.greaterThanOrEqual(this.quantityState)) {
+        log.debug('sendDecreaseCommand: Ignoring command {} for Item {} with state {}', value, this.name, this.state);
+        return false;
+      }
+    }
+
+    // value and current state are both numeric and value is greater than or equal current state
+    if (typeof value === 'number' && this.numericState !== null) {
+      if (value >= this.numericState) {
+        log.debug('sendDecreaseCommand: Ignoring command {} for Item {} with state {}', value, this.name, this.state);
+        return false;
+      }
+    }
+
+    // else send the command
+    log.debug('sendDecreaseCommand: Sending command {} to Item {} with state {}', value, this.name, this.state);
+    this.sendCommand(value);
+    return true;
+  }
+
+  /**
+   * Calculates the toggled state of this Item.
+   * For Items like Color and Dimmer, getStateAs(OnOffType) is used and the toggle calculated of that.
+   *
+   * @private
    * @returns the toggled state (e.g. 'OFF' if the Item is 'ON')
    * @throws error if the Item is uninitialized or is a type that doesn't make sense to toggle
    */
-  getToggleState () {
+  #getToggleState () {
     if (this.isUninitialized) {
       throw Error('Cannot toggle uninitialized Items');
     }
     switch (this.type) {
-      case 'PlayerItem' :
+      case 'Player' :
         return this.state === 'PAUSE' ? 'PLAY' : 'PAUSE';
-      case 'ContactItem' :
+      case 'Contact' :
         return this.state === 'OPEN' ? 'CLOSED' : 'OPEN';
       default: {
         const oldState = this.rawItem.getStateAs(OnOffType);
@@ -298,15 +359,14 @@ class Item {
   }
 
   /**
-   * Sends a command to flip the Item's state (e.g. if it is 'ON' an 'OFF'
-   * command is sent).
+   * Sends a command to flip the Item's state (e.g. if it is 'ON' an 'OFF' command is sent).
    * @throws error if the Item is uninitialized or a type that cannot be toggled or commanded
    */
   sendToggleCommand () {
-    if (this.type === 'ContactItem') {
+    if (this.type === 'Contact') {
       throw Error('Cannot command Contact Items');
     }
-    this.sendCommand(this.getToggleState());
+    this.sendCommand(this.#getToggleState());
   }
 
   /**
@@ -315,7 +375,7 @@ class Item {
    * @throws error if the Item is uninitialized or a type that cannot be toggled
    */
   postToggleUpdate () {
-    this.postUpdate(this.getToggleState());
+    this.postUpdate(this.#getToggleState());
   }
 
   /**

diff --git a/types/items/items.d.ts b/types/items/items.d.ts
@@ -254,16 +254,21 @@ export class Item {
      */
     sendCommandIfDifferent(value: string | number | time.ZonedDateTime | Quantity | HostState): boolean;
     /**
-     * Calculates the toggled state of this Item. For Items like Color and
-     * Dimmer, getStateAs(OnOffType) is used and the toggle calculated off
-     * of that.
-     * @returns the toggled state (e.g. 'OFF' if the Item is 'ON')
-     * @throws error if the Item is uninitialized or is a type that doesn't make sense to toggle
+     * Increase the value of this Item to the given value by sending a command, but only if the current state is less than that value.
+     *
+     * @param {number|Quantity|HostState} value the value of the command to send, such as 'ON'
+     * @return {boolean} true if the command was sent, false otherwise
+     */
+    sendIncreaseCommand(value: number | Quantity | HostState): boolean;
+    /**
+     * Decreases the value of this Item to the given value by sending a command, but only if the current state is greater than that value.
+     *
+     * @param {number|Quantity|HostState} value the value of the command to send, such as 'ON'
+     * @return {boolean} true if the command was sent, false otherwise
      */
-    getToggleState(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
+    sendDecreaseCommand(value: number | Quantity | HostState): boolean;
     /**
-     * Sends a command to flip the Item's state (e.g. if it is 'ON' an 'OFF'
-     * command is sent).
+     * Sends a command to flip the Item's state (e.g. if it is 'ON' an 'OFF' command is sent).
      * @throws error if the Item is uninitialized or a type that cannot be toggled or commanded
      */
     sendToggleCommand(): void;
@@ -312,6 +317,7 @@ export class Item {
      */
     removeTags(...tagNames: string[]): void;
     toString(): any;
+    #private;
 }
 import metadata = require("./metadata/metadata");
 import TimeSeries = require("./time-series");

diff --git a/types/items/items.d.ts.map b/types/items/items.d.ts.map
diff --git a/types/items/metadata/itemchannellink.d.ts b/types/items/metadata/itemchannellink.d.ts
@@ -31,7 +31,9 @@ export type Item = {
     };
     sendCommand(value: any): void;
     sendCommandIfDifferent(value: any): boolean;
-    getToggleState(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
+    sendIncreaseCommand(value: any): boolean;
+    sendDecreaseCommand(value: any): boolean;
+    "__#5@#getToggleState"(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
     sendToggleCommand(): void;
     postToggleUpdate(): void;
     postUpdate(value: any): void;

diff --git a/types/items/metadata/itemchannellink.d.ts.map b/types/items/metadata/itemchannellink.d.ts.map
diff --git a/types/items/metadata/metadata.d.ts b/types/items/metadata/metadata.d.ts
@@ -22,7 +22,9 @@ export type Item = {
     removeMetadata(namespace?: string): ItemMetadata;
     sendCommand(value: any): void;
     sendCommandIfDifferent(value: any): boolean;
-    getToggleState(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
+    sendIncreaseCommand(value: any): boolean;
+    sendDecreaseCommand(value: any): boolean;
+    "__#5@#getToggleState"(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
     sendToggleCommand(): void;
     postToggleUpdate(): void;
     postUpdate(value: any): void;

diff --git a/types/items/metadata/metadata.d.ts.map b/types/items/metadata/metadata.d.ts.map
diff --git a/types/quantity.d.ts b/types/quantity.d.ts
@@ -1,6 +1,10 @@
 export type Item = {
     rawItem: HostItem;
     persistence: import("./items/item-persistence");
+    /**
+     * QuantityError is thrown when {@link Quantity} creation or operation fails.
+     * It is used to wrap the underlying Java Exceptions and add some additional information and a JS stacktrace to it.
+     */
     semantics: import("./items/item-semantics");
     readonly type: string;
     readonly name: string;
@@ -31,7 +35,9 @@ export type Item = {
     };
     sendCommand(value: any): void;
     sendCommandIfDifferent(value: any): boolean;
-    getToggleState(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
+    sendIncreaseCommand(value: any): boolean;
+    sendDecreaseCommand(value: any): boolean;
+    "__#5@#getToggleState"(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
     sendToggleCommand(): void;
     postToggleUpdate(): void;
     postUpdate(value: any): void;

diff --git a/types/quantity.d.ts.map b/types/quantity.d.ts.map
diff --git a/types/rules/operation-builder.d.ts b/types/rules/operation-builder.d.ts
@@ -31,7 +31,9 @@ export type Item = {
     };
     sendCommand(value: any): void;
     sendCommandIfDifferent(value: any): boolean;
-    getToggleState(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
+    sendIncreaseCommand(value: any): boolean;
+    sendDecreaseCommand(value: any): boolean;
+    "__#5@#getToggleState"(): "PAUSE" | "PLAY" | "OPEN" | "CLOSED" | "ON" | "OFF";
     sendToggleCommand(): void;
     postToggleUpdate(): void;
     postUpdate(value: any): void;