[items] Rename _toOpenhabType method _toOpenhabPrimitiveType & Improv…

…e JSDoc

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

src/helpers.js

@@ -22,17 +22,19 @@ function _getItemName (itemOrName) {
 }
 
 /**
- * Helper function to convert JS types to a
- * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/types/type org.openhab.core.types.Type} or a valid string representation of a type.
+ * Helper function to convert a JS type to a primitive type accepted by openHAB Core, which often is a string representation of the type.
  *
- * Number and string are passed through.
- * Other objects should implement <code>toOpenHabString</code> (prioritized) or <code>toString</code> to return an openHAB compatible representation.
+ * Converting any complex type to a primitive type is required to avoid multi-threading issues (as GraalJS does not allow multithreaded access to a script's context),
+ * e.g. when passing objects to persistence, which then persists asynchronously.
+ *
+ * Number and string primitives are passed through.
+ * Objects should implement <code>toOpenHabString</code> (prioritized) or <code>toString</code> to return an openHAB Core compatible string representation.
  *
  * @private
  * @param {*} value
  * @returns {*}
  */
-function _toOpenhabType (value) {
+function _toOpenhabPrimitiveType (value) {
   if (value === null) return 'NULL';
   if (value === undefined) return 'UNDEF';
   if (typeof value === 'number' || typeof value === 'string') {
@@ -107,7 +109,7 @@ function _isDuration (o) {
 
 module.exports = {
   _getItemName,
-  _toOpenhabType,
+  _toOpenhabPrimitiveType,
   _isItem,
   _isQuantity,
   _isZonedDateTime,

src/items/item-persistence.js

@@ -9,7 +9,7 @@ const utils = require('../utils');
  * @private
  */
 const { getQuantity, QuantityError } = require('../quantity');
-const { _toOpenhabType } = require('../helpers');
+const { _toOpenhabPrimitiveType } = require('../helpers');
 const PersistenceExtensions = Java.type('org.openhab.core.persistence.extensions.PersistenceExtensions');
 
 /**
@@ -166,10 +166,10 @@ class ItemPersistence {
     switch (arguments.length) {
       // persist a given state at a given timestamp
       case 2:
-        PersistenceExtensions.persist(this.rawItem, timestamp, _toOpenhabType(state));
+        PersistenceExtensions.persist(this.rawItem, timestamp, _toOpenhabPrimitiveType(state));
         break;
       case 3:
-        PersistenceExtensions.persist(this.rawItem, timestamp, _toOpenhabType(state), serviceId);
+        PersistenceExtensions.persist(this.rawItem, timestamp, _toOpenhabPrimitiveType(state), serviceId);
         break;
       // persist the current state or a TimeSeries
       default:

src/items/items.js

@@ -7,7 +7,7 @@
 const osgi = require('../osgi');
 const utils = require('../utils');
 const log = require('../log')('items');
-const { _toOpenhabType } = require('../helpers');
+const { _toOpenhabPrimitiveType } = require('../helpers');
 const { getQuantity, QuantityError } = require('../quantity');
 
 const { UnDefType, OnOffType, events, itemRegistry } = require('@runtime');
@@ -234,7 +234,7 @@ class Item {
    * @see postUpdate
    */
   sendCommand (value) {
-    events.sendCommand(this.rawItem, _toOpenhabType(value));
+    events.sendCommand(this.rawItem, _toOpenhabPrimitiveType(value));
   }
 
   /**
@@ -245,7 +245,7 @@ class Item {
    * @see sendCommand
    */
   sendCommandIfDifferent (value) {
-    value = _toOpenhabType(value);
+    value = _toOpenhabPrimitiveType(value);
     if (value.toString() !== this.state) {
       this.sendCommand(value);
       return true;
@@ -309,7 +309,7 @@ class Item {
    * @see sendCommand
    */
   postUpdate (value) {
-    events.postUpdate(this.rawItem, _toOpenhabType(value));
+    events.postUpdate(this.rawItem, _toOpenhabPrimitiveType(value));
   }
 
   /**