[Quantity] Initial contribution: Support UoM handling by wrapping Qua…

…ntityType (#206)

* [quantities] Intitial contribution of QuantityType wrapper
* [quantities] Add JSDoc
* [quantities] Rename to quantity
* [quantity] Add type definitions
* [quantity] Export from library
* Update CHANGELOG

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

CHANGELOG.md

@@ -10,6 +10,7 @@
 | Enhancement | `time`     | Support ISO8601 string parsing in `toZDT`                                | [#202](https://github.com/openhab/openhab-js/pull/202) | No       |
 | Enhancement | `time`     | Add `isBetweenDates` & `isBetweenDateTimes` polyfills to `ZonedDateTime` | [#203](https://github.com/openhab/openhab-js/pull/203) | No       |
 | Enhancement | `items`    | ItemHistory: ItemHistory: Add `previousStateTimestamp` method            | [#205](https://github.com/openhab/openhab-js/pull/205) | No       |
+| Enhancement | `Quantity` | Add UoM/Quantity handling functionality by wrapping QuantityType         | [#206](https://github.com/openhab/openhab-js/pull/206) | No       |
 
 Also see the [Release Milestone](https://github.com/openhab/openhab-js/milestone/10).
 

index.js

@@ -29,5 +29,6 @@ module.exports = {
   get utils () { return require('./utils'); },
   get osgi () { return require('./osgi'); },
   get cache () { return require('./cache'); },
-  get time () { return require('./time'); }
+  get time () { return require('./time'); },
+  get Quantity () { return require('./quantity'); }
 };

quantity.js

@@ -0,0 +1,219 @@
+/** {@link https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/quantitytype org.openhab.core.library.types.QuantityType} */
+const QuantityType = Java.type('org.openhab.core.library.types.QuantityType');
+/** {@link https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/math/BigDecimal.html java.math.BigDecimal} */
+const BigDecimal = Java.type('java.math.BigDecimal');
+
+/**
+ * Class allowing easy Units of Measurement/Quantity handling by wrapping the openHAB {@link QuantityType}.
+ *
+ * @hideconstructor
+ */
+class Quantity {
+  /**
+   * @param {string} value a string consisting of a numeric value and a dimension, e.g. `5.5 m`
+   */
+  constructor (value) {
+    if (typeof value !== 'string') throw new TypeError('Wrong argument provided to factory, provide a string!');
+    /**
+     * @type {QuantityType}
+     * @private
+     */
+    this.raw = new QuantityType(value);
+  }
+
+  /**
+   * Dimension of this Quantity, e.g. `[L]` for metres or `[L]²` for cubic-metres.
+   * @returns {string}
+   */
+  get dimension () {
+    return this.raw.getDimension().toString();
+  }
+
+  /**
+   * Unit of this Quantity, e.g. `Metre`.
+   * @returns {string|null}
+   */
+  get unit () {
+    const unit = this.raw.getUnit().getName();
+    return (unit === null) ? null : unit.toString();
+  }
+
+  /**
+   * Unit symbol of this Quantitiy, e.g. `m`.
+   * @returns {string|null}
+   */
+  get symbol () {
+    const symbol = this.raw.getUnit().getSymbol();
+    return (symbol === null) ? null : symbol.toString();
+  }
+
+  /**
+   * Float (decimal number) value of this Quantity.
+   * @returns {number}
+   */
+  get float () {
+    return parseFloat(this.raw.doubleValue());
+  }
+
+  /**
+   * Integer (non-decimal number) value of this Quantity.
+   * @returns {number}
+   */
+  get int () {
+    return parseInt(this.raw.longValue());
+  }
+
+  /**
+   * Add the given value to this Quantity.
+   * @param {string|Quantity} value
+   * @returns {Quantity} this Quantity
+   */
+  add (value) {
+    value = this._stringOrQtyToQtyType(value);
+    this.raw = this.raw.add(value);
+    return this;
+  }
+
+  /**
+   * Divide this Quantity by the given value.
+   * @param {number|string|Quantity} value
+   * @returns {Quantity} this Quantity
+   */
+  divide (value) {
+    value = this._stringOrNumberOrQtyToQtyType(value);
+    this.raw = this.raw.divide(value);
+    return this;
+  }
+
+  /**
+   * Multiply this Quantity by the given value.
+   * @param {number|string|Quantity} value
+   * @returns {Quantity} this Quantity
+   */
+  multiply (value) {
+    value = this._stringOrNumberOrQtyToQtyType(value);
+    this.raw = this.raw.multiply(value);
+    return this;
+  }
+
+  /**
+   * Subtract the given value from this Quantity.
+   * @param {string|Quantity} value
+   * @returns {Quantity} this Quantity
+   */
+  subtract (value) {
+    value = this._stringOrQtyToQtyType(value);
+    this.raw = this.raw.subtract(value);
+    return this;
+  }
+
+  /**
+   * Convert this Quantity to the given unit.
+   * @param {string} unit
+   * @returns {Quantity} this with the new unit
+   */
+  toUnit (unit) {
+    this.raw = this.raw.toUnit(unit);
+    return this;
+  }
+
+  /**
+   * Checks whether this Quantity is equal to the passed in value.
+   * @param {string|Quantity} value
+   * @returns {boolean}
+   */
+  equal (value) {
+    value = this._stringOrQtyToQtyType(value);
+    return this.raw.compareTo(value) === 0;
+  }
+
+  /**
+   * Checks whether this Quantity is larger than the passed in value.
+   * @param {string|Quantity} value
+   * @returns {boolean}
+   */
+  largerThan (value) {
+    value = this._stringOrQtyToQtyType(value);
+    return this.raw.compareTo(value) > 0;
+  }
+
+  /**
+   * Checks whether this Quantity is larger than or equal to the passed in value.
+   * @param {string|Quantity} value
+   * @returns {boolean}
+   */
+  largerThanOrEqual (value) {
+    value = this._stringOrQtyToQtyType(value);
+    return this.raw.compareTo(value) >= 0;
+  }
+
+  /**
+   * Checks whether this Quantity is smaller than the passed in value.
+   * @param {string|Quantity} value
+   * @returns {boolean}
+   */
+  smallerThan (value) {
+    value = this._stringOrQtyToQtyType(value);
+    return this.raw.compareTo(value) < 0;
+  }
+
+  /**
+   * Checks whether this Quantity is smaller than or equal to the passed in value.
+   * @param {string|Quantity} value
+   * @returns {boolean}
+   */
+  smallerThanOrEqual (value) {
+    value = this._stringOrQtyToQtyType(value);
+    return this.raw.compareTo(value) <= 0;
+  }
+
+  toString () {
+    return this.raw.toString();
+  }
+
+  /**
+     * Takes either a {@link Quantity}, a `string` or a `number` and converts it to a {@link QuantityType} or {@link BigDecimal}.
+     * @param {number|string|Quantity} value
+     * @returns {BigDecimal|QuantityType}
+     * @throws {TypeError} if parameter has the wrong type
+     * @private
+     */
+  _stringOrNumberOrQtyToQtyType (value) {
+    if (typeof value === 'number') {
+      value = new BigDecimal(value);
+    } else if (typeof value === 'string') {
+      value = new QuantityType(value);
+    } else if (value instanceof Quantity) {
+      value = value.raw;
+    } else {
+      throw new TypeError('Wrong argument type provided, please provide a number or string or Quantity.');
+    }
+    return value;
+  }
+
+  /**
+     * Takes either a {@link Quantity} or a `string` and converts it to a {@link QuantityType}.
+     * @param {string|Quantity} value
+     * @returns {QuantityType}
+     * @throws {TypeError} if parameter has the wrong type
+     * @private
+     */
+  _stringOrQtyToQtyType (value) {
+    if (typeof value === 'string') {
+      value = new QuantityType(value);
+    } else if (value instanceof Quantity) {
+      value = value.raw;
+    } else {
+      throw new TypeError('Wrong argument type provided, please provide a string or Quantity.');
+    }
+    return value;
+  }
+}
+
+/**
+ * The Quantity allows easy Units of Measurement/Quantity handling by wrapping the openHAB {@link QuantityType}.
+ *
+ * @param {string} value a string consisting of a numeric value and a dimension, e.g. `5.5 m`
+ * @returns {Quantity}
+ */
+module.exports = (value) => new Quantity(value);

types/openhab-js.d.ts

@@ -35,4 +35,5 @@ export const utils: typeof import("./utils");
 export const osgi: typeof import("./osgi");
 export const cache: typeof import("./cache");
 export const time: typeof import("./time");
+export const Quantity: typeof import("./quantity");
 export {};

types/quantity.d.ts

@@ -0,0 +1,121 @@
+declare function _exports(value: string): Quantity;
+export = _exports;
+/**
+ * Class allowing easy Units of Measurement/Quantity handling by wrapping the openHAB {@link QuantityType}.
+ *
+ * @hideconstructor
+ */
+declare class Quantity {
+    /**
+     * @param {string} value a string consisting of a numeric value and a dimension, e.g. `5.5 m`
+     */
+    constructor(value: string);
+    /**
+     * @type {QuantityType}
+     * @private
+     */
+    private raw;
+    /**
+     * Dimension of this Quantity, e.g. `[L]` for metres or `[L]²` for cubic-metres.
+     * @returns {string}
+     */
+    get dimension(): string;
+    /**
+     * Unit of this Quantity, e.g. `Metre`.
+     * @returns {string|null}
+     */
+    get unit(): string;
+    /**
+     * Unit symbol of this Quantitiy, e.g. `m`.
+     * @returns {string|null}
+     */
+    get symbol(): string;
+    /**
+     * Float (decimal number) value of this Quantity.
+     * @returns {number}
+     */
+    get float(): number;
+    /**
+     * Integer (non-decimal number) value of this Quantity.
+     * @returns {number}
+     */
+    get int(): number;
+    /**
+     * Add the given value to this Quantity.
+     * @param {string|Quantity} value
+     * @returns {Quantity} this Quantity
+     */
+    add(value: string | Quantity): Quantity;
+    /**
+     * Divide this Quantity by the given value.
+     * @param {number|string|Quantity} value
+     * @returns {Quantity} this Quantity
+     */
+    divide(value: number | string | Quantity): Quantity;
+    /**
+     * Multiply this Quantity by the given value.
+     * @param {number|string|Quantity} value
+     * @returns {Quantity} this Quantity
+     */
+    multiply(value: number | string | Quantity): Quantity;
+    /**
+     * Subtract the given value from this Quantity.
+     * @param {string|Quantity} value
+     * @returns {Quantity} this Quantity
+     */
+    subtract(value: string | Quantity): Quantity;
+    /**
+     * Convert this Quantity to the given unit.
+     * @param {string} unit
+     * @returns {Quantity} this with the new unit
+     */
+    toUnit(unit: string): Quantity;
+    /**
+     * Checks whether this Quantity is equal to the passed in value.
+     * @param {string|Quantity} value
+     * @returns {boolean}
+     */
+    equal(value: string | Quantity): boolean;
+    /**
+     * Checks whether this Quantity is larger than the passed in value.
+     * @param {string|Quantity} value
+     * @returns {boolean}
+     */
+    largerThan(value: string | Quantity): boolean;
+    /**
+     * Checks whether this Quantity is larger than or equal to the passed in value.
+     * @param {string|Quantity} value
+     * @returns {boolean}
+     */
+    largerThanOrEqual(value: string | Quantity): boolean;
+    /**
+     * Checks whether this Quantity is smaller than the passed in value.
+     * @param {string|Quantity} value
+     * @returns {boolean}
+     */
+    smallerThan(value: string | Quantity): boolean;
+    /**
+     * Checks whether this Quantity is smaller than or equal to the passed in value.
+     * @param {string|Quantity} value
+     * @returns {boolean}
+     */
+    smallerThanOrEqual(value: string | Quantity): boolean;
+    toString(): any;
+    /**
+       * Takes either a {@link Quantity}, a `string` or a `number` and converts it to a {@link QuantityType} or {@link BigDecimal}.
+       * @param {number|string|Quantity} value
+       * @returns {BigDecimal|QuantityType}
+       * @throws {TypeError} if parameter has the wrong type
+       * @private
+       */
+    private _stringOrNumberOrQtyToQtyType;
+    /**
+       * Takes either a {@link Quantity} or a `string` and converts it to a {@link QuantityType}.
+       * @param {string|Quantity} value
+       * @returns {QuantityType}
+       * @throws {TypeError} if parameter has the wrong type
+       * @private
+       */
+    private _stringOrQtyToQtyType;
+}
+//# sourceMappingURL=quantity.d.ts.map