[actions] Add Transformation Actions as a class & Add arg type checki…

…ng lib (#180)

* README: Add Transformation Actions
* [actions] Explicitely add Transformation
This adds a Transformation class to explicitely allow access to the
Transformation Actions, which were dynamically exported before.
* Add `typeof-arguments` to dependencies
* Update type defs
* Update CHANGELOG

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

CHANGELOG.md

@@ -6,6 +6,7 @@
 |-------------|-----------|---------------------------------------------------------------------|--------------------------------------------------------|----------|
 | Enhancement | `items`   | ItemHistory: Change return types of min/max between/since to number | [#175](https://github.com/openhab/openhab-js/pull/175) | Yes      |
 | Cleanup     | `rules`   | Remove unused rule providers                                        | [#183](https://github.com/openhab/openhab-js/pull/183) | Yes      |
+| Enhancement | `actions` | Add Transformation actions as a class with arg type checking        | [#180](https://github.com/openhab/openhab-js/pull/180) | No       |
 
 Also see the [Release Milestone](https://github.com/openhab/openhab-js/milestone/8).
 

README.md

@@ -627,6 +627,18 @@ It is possible to get the actions for a Thing using `actions.Things.getActions(b
 
 See [openhab-js : actions.Things](https://openhab.github.io/openhab-js/actions.html#.Things) for complete documentation.
 
+#### Transformation Actions
+
+openHAB provides various [data transformation services](https://www.openhab.org/addons/#transform) which can translate between technical and human-readable values.
+Usually, they are used directly on Items, but it is also possible to access them from scripts.
+
+```javascript
+console.log(actions.Transformation.transform('MAP', 'en.map', 'OPEN')); // open
+console.log(actions.Transformation.transform('MAP', 'de.map', 'OPEN')); // offen
+```
+
+See [openhab-js : actions.Transformation](https://openhab.github.io/openhab-js/actions.Transformation.html) for complete documentation.
+
 #### Voice Actions
 
 See [openhab-js : actions.Voice](https://openhab.github.io/openhab-js/actions.html#.Voice) for complete documentation.

actions.js

@@ -14,14 +14,17 @@
  * actions.NotificationAction.sendBroadcastNotification("Hello World!")
  */
 
+const typeOfArguments = require('typeof-arguments');
 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 JavaScriptExecution = Java.type('org.openhab.core.model.script.actions.ScriptExecution');
+const JavaTransformation = Java.type('org.openhab.core.transform.actions.Transformation');
 
 // Dynamically export all found actions
 const dynamicExports = {};
@@ -299,6 +302,51 @@ const Semantics = Java.type('org.openhab.core.model.script.actions.Semantics');
  */
 const ThingsAction = Java.type('org.openhab.core.model.script.actions.Things');
 
+/**
+ * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/transform/actions/transformation Transformation} Actions
+ *
+ * The static methods of this class allow rules to execute transformations using one of the various {@link https://www.openhab.org/addons/#transform data transformation services}.
+ *
+ * @example
+ * actions.Transformation.transform('MAP', 'en.map', 'OPEN'); // returns "open"
+ * actions.Transformation.transform('MAP', 'de.map', 'OPEN'); // returns "offen"
+ * @memberof actions
+ * @hideconstructor
+ */
+class Transformation {
+  /**
+   * Applies a transformation of a given type with some function to a value.
+   *
+   * @param {string} type the transformation type, e.g. REGEX or MAP
+   * @param {string} fn the function to call, this value depends on the transformation type
+   * @param {string} value the value to apply the transformation to
+   * @returns {string} the transformed value or the original one, if there was no service registered for the given type or a transformation exception occurred
+   */
+  static transform (type, fn, value) {
+    typeOfArguments(arguments, ['string', 'string', 'string']);
+    return JavaTransformation.transform(type, fn, value).toString();
+  }
+
+  /**
+   * Applies a transformation of a given type with some function to a value.
+   *
+   * @param {string} type the transformation type, e.g. REGEX or MAP
+   * @param {string} fn the function to call, this value depends on the transformation type
+   * @param {string} value the value to apply the transformation to
+   * @returns {string} the transformed value
+   * @throws Java {@link https://www.openhab.org/javadoc/latest/org/openhab/core/transform/TransformationException.html TransformationException}
+   */
+  static transformRaw (type, fn, value) {
+    typeOfArguments(arguments, ['string', 'string', 'string']);
+    // Wrap exception to enable JS stack traces
+    try {
+      return JavaTransformation.transformRaw(type, fn, value).toString();
+    } catch (error) {
+      throw new Error(error);
+    }
+  }
+}
+
 /**
  * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/Voice.html Voice} Actions
  *
@@ -354,6 +402,7 @@ module.exports = Object.assign(dynamicExports, {
   ScriptExecution,
   Semantics,
   Things: ThingsAction,
+  Transformation,
   Voice,
   NotificationAction,
   /**

package.json

@@ -14,7 +14,8 @@
     "dependencies": {
         "@js-joda/core": "^4.3.1",
         "@js-joda/timezone": "^2.11.1",
-        "parse-duration": "^0.1.1"
+        "parse-duration": "^0.1.1",
+        "typeof-arguments": "^5.1.3"
     },
     "scripts": {
         "test:mocha": "mocha test/**/*.test.js",

types/actions.d.ts

@@ -223,6 +223,38 @@ export const Semantics: any;
  * @memberof actions
  */
 declare const ThingsAction: any;
+/**
+ * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/transform/actions/transformation Transformation} Actions
+ *
+ * The static methods of this class allow rules to execute transformations using one of the various {@link https://www.openhab.org/addons/#transform data transformation services}.
+ *
+ * @example
+ * actions.Transformation.transform('MAP', 'en.map', 'OPEN'); // returns "open"
+ * actions.Transformation.transform('MAP', 'de.map', 'OPEN'); // returns "offen"
+ * @memberof actions
+ * @hideconstructor
+ */
+export class Transformation {
+    /**
+     * Applies a transformation of a given type with some function to a value.
+     *
+     * @param {string} type the transformation type, e.g. REGEX or MAP
+     * @param {string} fn the function to call, this value depends on the transformation type
+     * @param {string} value the value to apply the transformation to
+     * @returns {string} the transformed value or the original one, if there was no service registered for the given type or a transformation exception occurred
+     */
+    static transform(type: string, fn: string, value: string, ...args: any[]): string;
+    /**
+     * Applies a transformation of a given type with some function to a value.
+     *
+     * @param {string} type the transformation type, e.g. REGEX or MAP
+     * @param {string} fn the function to call, this value depends on the transformation type
+     * @param {string} value the value to apply the transformation to
+     * @returns {string} the transformed value
+     * @throws Java {@link https://www.openhab.org/javadoc/latest/org/openhab/core/transform/TransformationException.html TransformationException}
+     */
+    static transformRaw(type: string, fn: string, value: string, ...args: any[]): string;
+}
 /**
  * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/Voice.html Voice} Actions
  *