[actions] Export CoreUtil actions (#319)

Fixes #317.

Signed-off-by: Florian Hotze <[email protected]>

README.md

@@ -593,18 +593,28 @@ thing.setEnabled(false);
 The actions namespace allows interactions with openHAB actions.
 The following are a list of standard actions.
 
-Note that most of the actions currently do **not** provide type definitions and therefore auto-completion does not work.
+**Warning:** Please be aware, that (unless not explicitly noted) there is **no** type conversion from Java to JavaScript types for the return values of actions.
+Read the JavaDoc linked from the JSDoc to learn about the returned Java types.
+
+Please note that most of the actions currently do **not** provide type definitions and therefore auto-completion does not work.
 
 See [openhab-js : actions](https://openhab.github.io/openhab-js/actions.html) for full API documentation and additional actions.
 
 #### Audio Actions
 
 See [openhab-js : actions.Audio](https://openhab.github.io/openhab-js/actions.html#.Audio) for complete documentation.
 
-#### BusEvent
+#### BusEvent Actions
 
 See [openhab-js : actions.BusEvent](https://openhab.github.io/openhab-js/actions.html#.BusEvent) for complete documentation.
 
+#### CoreUtil Actions
+
+See [openhab-js : actions.CoreUtil](https://openhab.github.io/openhab-js/actions.html#.CoreUtil) for complete documentation.
+
+The `CoreUtil` actions provide access to parts of the utilities included in openHAB core, see [org.openhab.core.util](https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary).
+These include several methods to convert between color types like HSB, RGB, sRGB, RGBW and XY.
+
 #### Ephemeris Actions
 
 See [openhab-js : actions.Ephemeris](https://openhab.github.io/openhab-js/actions.html#.Ephemeris) for complete documentation.

actions.js

@@ -3,15 +3,22 @@
 /**
  * Actions namespace.
  *
- * This namespace provides access to openHAB actions. {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/package-summary.html All available actions} can be accessed as direct properties of this
- * object (via their simple class name).
+ * This namespace provides access to openHAB actions.
+ * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/package-summary.html All available actions} can be accessed as direct properties of this object (via their simple class name).
+ *
+ * WARNING: Please be aware that there is, unless otherwise noted, NO type conversion from Java to JavaScript types for the return values of actions.
+ * Read the linked JavaDoc to learn about the returned Java types.
  *
  * Additional actions provided by user installed addons can be accessed using their common name on the actions name space if the addon exports them in a proper way.
  *
+ * @example
+ * const { actions, time } = require('openhab');
+ * <caption>Send a broadcast notification</caption>
+ * actions.NotificationAction.sendBroadcastNotification('Hello World!');
+ * <caption>Schedule a function for later execution/Create a timer (advanced)</caption>
+ * actions.ScriptExecution.createTimer('myTimer', time.toZDT().plusMinutes(10), () => { console.log('Hello timer!'); });
+ *
  * @namespace actions
- * @example <caption>Sends a broadcast notification</caption>
- * const { actions } = require('openhab');
- * actions.NotificationAction.sendBroadcastNotification("Hello World!")
  */
 /**
  * @typedef {import('@js-joda/core').ZonedDateTime} time.ZonedDateTime
@@ -20,12 +27,12 @@
 
 const osgi = require('./osgi');
 // See https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/internal/defaultscope/ScriptThingActionsImpl.java
-const { actions } = require('@runtime/Defaults');
 const log = require('./log')('actions');
 
 const Things = Java.type('org.openhab.core.model.script.actions.Things');
 const actionServices = osgi.findServices('org.openhab.core.model.script.engine.action.ActionService', null) || [];
 
+const JavaCoreUtil = Java.type('org.openhab.core.model.script.actions.CoreUtil');
 const JavaScriptExecution = Java.type('org.openhab.core.model.script.actions.ScriptExecution');
 const JavaTransformation = Java.type('org.openhab.core.transform.actions.Transformation');
 
@@ -86,6 +93,26 @@ const Audio = Java.type('org.openhab.core.model.script.actions.Audio');
  */
 const BusEvent = Java.type('org.openhab.core.model.script.actions.BusEvent');
 
+/**
+ * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/coreutil CoreUtil} Actions
+ *
+ * This class provides static methods mapping methods from package {@link https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary org.openhab.core.util}.
+ *
+ * Its functionality includes:
+ * @example
+ * CoreUtil.hsbToRgb(HSBType hsb) -> int[]
+ * CoreUtil.hsbToRgbPercent(HSBType hsb) -> PercentType[]
+ * CoreUtil.hsbTosRGB(HSBType hsb) -> int
+ * CoreUtil.hsbToRgbw(HSBType hsb) -> int[]
+ * CoreUtil.hsbToRgbwPercent(HSBType hsb) -> PercentType[]
+ * CoreUtil.rgbToHsb(int[] rgb) -> HSBType
+ * CoreUtil.rgbToHsb(PercentType[] rgb) -> HSBType
+ *
+ * @name CoreUtil
+ * @memberof actions
+ */
+const CoreUtil = JavaCoreUtil;
+
 /**
  * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris Ephemeris} Actions
  *
@@ -228,7 +255,7 @@ class ScriptExecution {
    *   console.log(foo + bar);
    * }, 'Hello', 'openHAB');
    *
-   * @param {string} identifier an optional identifier, e.g. user for logging
+   * @param {string} identifier an optional identifier, e.g. used for logging
    * @param {time.ZonedDateTime} zdt the point in time when the callback function should be executed
    * @param {function} functionRef callback function to execute when the timer expires
    * @param {...*} params additional arguments which are passed through to the function specified by `functionRef`
@@ -259,7 +286,7 @@ class ScriptExecution {
    * Schedules a function (with argument) for later execution
    *
    * @deprecated
-   * @param {string} identifier an optional identifier
+   * @param {string} identifier an optional identifier, e.g. used for logging
    * @param {time.ZonedDateTime} instant the point in time when the code should be executed
    * @param {*} arg1 the argument to pass to the code block
    * @param {function} closure the code block to execute
@@ -281,7 +308,7 @@ class ScriptExecution {
  *
  * The static methods of this class are made available as functions in the scripts. This allows a script to use Semantics features.
  *
- * Instead of using the Semantics actions, it is recommended to use the the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}.
+ * Instead of using the Semantics actions, it is recommended to use the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}.
  *
  * @example
  * Semantics.getEquipment(Item item)
@@ -405,6 +432,7 @@ try {
 module.exports = Object.assign(dynamicExports, {
   Audio,
   BusEvent,
+  CoreUtil,
   Ephemeris,
   Exec,
   HTTP,
@@ -425,7 +453,7 @@ module.exports = Object.assign(dynamicExports, {
    * @param {string} thingUid Thing UID
    * @returns {*} Native Java {@link https://www.openhab.org/javadoc/latest/org/openhab/core/thing/binding/thingactions ThingActions}
    */
-  get: (bindingId, thingUid) => actions.get(bindingId, thingUid),
+  get: (bindingId, thingUid) => Things.getActions(bindingId, thingUid),
   /**
    * Get the ThingActions of a given Thing.
    * Duplicate of {@link actions.get actions.get()} and {@link actions.Things actions.Things.getActions()}.

types/actions.d.ts

@@ -41,6 +41,25 @@ export const Audio: any;
  * @memberof actions
  */
 export const BusEvent: any;
+/**
+ * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/coreutil CoreUtil} Actions
+ *
+ * This class provides static methods mapping methods from package {@link https://www.openhab.org/javadoc/latest/org/openhab/core/util/package-summary org.openhab.core.util}.
+ *
+ * Its functionality includes:
+ * @example
+ * CoreUtil.hsbToRgb(HSBType hsb) -> int[]
+ * CoreUtil.hsbToRgbPercent(HSBType hsb) -> PercentType[]
+ * CoreUtil.hsbTosRGB(HSBType hsb) -> int
+ * CoreUtil.hsbToRgbw(HSBType hsb) -> int[]
+ * CoreUtil.hsbToRgbwPercent(HSBType hsb) -> PercentType[]
+ * CoreUtil.rgbToHsb(int[] rgb) -> HSBType
+ * CoreUtil.rgbToHsb(PercentType[] rgb) -> HSBType
+ *
+ * @name CoreUtil
+ * @memberof actions
+ */
+export const CoreUtil: any;
 /**
  * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris Ephemeris} Actions
  *
@@ -175,7 +194,7 @@ export class ScriptExecution {
      *   console.log(foo + bar);
      * }, 'Hello', 'openHAB');
      *
-     * @param {string} identifier an optional identifier, e.g. user for logging
+     * @param {string} identifier an optional identifier, e.g. used for logging
      * @param {time.ZonedDateTime} zdt the point in time when the callback function should be executed
      * @param {function} functionRef callback function to execute when the timer expires
      * @param {...*} params additional arguments which are passed through to the function specified by `functionRef`
@@ -186,7 +205,7 @@ export class ScriptExecution {
      * Schedules a function (with argument) for later execution
      *
      * @deprecated
-     * @param {string} identifier an optional identifier
+     * @param {string} identifier an optional identifier, e.g. used for logging
      * @param {time.ZonedDateTime} instant the point in time when the code should be executed
      * @param {*} arg1 the argument to pass to the code block
      * @param {function} closure the code block to execute
@@ -199,7 +218,7 @@ export class ScriptExecution {
  *
  * The static methods of this class are made available as functions in the scripts. This allows a script to use Semantics features.
  *
- * Instead of using the Semantics actions, it is recommended to use the the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}.
+ * Instead of using the Semantics actions, it is recommended to use the {@link items.ItemSemantics} available through the `semantics` property of an {@link items.Item}.
  *
  * @example
  * Semantics.getEquipment(Item item)