[environment] Add version fields, rename isFileBasedScript -> isScriptFile

README.md

@@ -1323,6 +1323,14 @@ openHAB-JS converts between Java and JavaScript data types and reverse.
 
 See [openhab-js : utils](https://openhab.github.io/openhab-js/utils.html) for full API documentation.
 
+### Environment
+
+The `environment` namespace provides information about the environment of the script, like openHAB, [openhab-js](https://github.com/openhab/openhab-js) & GraalJS versions.
+
+A word of caution: The `environment` namespace is considered an advanced API and might change without a new major version of [openhab-js](https://github.com/openhab/openhab-js).
+
+See [openhab-js : environment](https://openhab.github.io/openhab-js/environment.html) for full API documentation.
+
 ## File Based Rules
 
 The JavaScript Scripting automation add-on will load `.js` scripts from `automation/js` in the user configuration directory.

src/environment.js

@@ -1,21 +1,50 @@
 // This module MUST NOT depend on any other library code to avoid circular dependencies
 
+const FrameworkUtil = Java.type('org.osgi.framework.FrameworkUtil');
+
 /**
  * Environment namespace.
  * This namespace handles utilities for determining the script environment and retrieving information about it.
+ * A word of caution: This namespace is considered an advanced API and might change without a new major version of the library.
  *
  * @namespace environment
  */
 
 /**
- * Returns whether the code is running from a file-based script.
+ * openHAB version
+ *
+ * @memberOf environment
+ * @name OPENHAB_VERSION
+ * @type {string}
+ */
+const OPENHAB_VERSION = FrameworkUtil.getBundle(Java.type('org.openhab.core.OpenHAB')).getVersion().toString();
+
+/**
+ * openHAB JavaScript library version
+ *
+ * @memberOf environment
+ * @name OPENHAB_JS_VERSION
+ * @type {string}
+ */
+const OPENHAB_JS_VERSION = require('../package.json').version;
+
+/**
+ * GraalJS version
+ * @memberOf environment
+ * @name GRAALJS_VERSION
+ * @type {string}
+ */
+const GRAALJS_VERSION = FrameworkUtil.getBundle(Java.type('org.graalvm.polyglot.Context')).getVersion().toString();
+
+/**
+ * Returns whether the code is from a script file.
  * This is determined by checking if the `javax.script.filename` global variable is defined.
  * This is useful to distinguish between file-based scripts and UI-based scripts in openHAB.
  *
  * @memberOf environment
  * @return {boolean} true if the script is file-based, false otherwise
  */
-function isFileBasedScript () {
+function isScriptFile () {
   return globalThis['javax.script.filename'] !== undefined;
 }
 
@@ -37,10 +66,13 @@ function _hasProviderSupport () {
  * @return {boolean} true if the provider registry implementations should be used, false otherwise
  */
 function useProviderRegistries () {
-  return _hasProviderSupport() && isFileBasedScript();
+  return _hasProviderSupport() && isScriptFile();
 }
 
 module.exports = {
-  isFileBasedScript,
-  useProviderRegistries
+  isScriptFile,
+  useProviderRegistries,
+  OPENHAB_VERSION,
+  OPENHAB_JS_VERSION,
+  GRAALJS_VERSION
 };

src/utils.js

@@ -1,11 +1,12 @@
 /**
  * openHAB JavaScript library version
  *
+ * @deprecated use {@link environment.OPENHAB_JS_VERSION} instead
  * @memberof utils
  * @name OPENHAB_JS_VERSION
  * @type {string}
  */
-const VERSION = require('../package.json').version;
+const OPENHAB_JS_VERSION = require('../package.json').version;
 const log = require('./log')('utils');
 
 const HashSet = Java.type('java.util.HashSet');
@@ -203,5 +204,5 @@ module.exports = {
   javaMapToJsObj,
   randomUUID,
   dumpObject,
-  OPENHAB_JS_VERSION: VERSION
+  OPENHAB_JS_VERSION
 };

types/environment.d.ts

@@ -1,18 +1,12 @@
 /**
- * Environment namespace.
- * This namespace handles utilities for determining the script environment and retrieving information about it.
- *
- * @namespace environment
- */
-/**
- * Returns whether the code is running from a file-based script.
+ * Returns whether the code is from a script file.
  * This is determined by checking if the `javax.script.filename` global variable is defined.
  * This is useful to distinguish between file-based scripts and UI-based scripts in openHAB.
  *
  * @memberOf environment
  * @return {boolean} true if the script is file-based, false otherwise
  */
-export function isFileBasedScript(): boolean;
+export function isScriptFile(): boolean;
 /**
  * Returns whether the registry implementations from the `@runtime/provider` module should be used instead of the default ones from the `@runtime` module.
  * Provider implementations should be used if the host openHAB version supports it and the script is running from a file-based script.
@@ -21,4 +15,34 @@ export function isFileBasedScript(): boolean;
  * @return {boolean} true if the provider registry implementations should be used, false otherwise
  */
 export function useProviderRegistries(): boolean;
+/**
+ * Environment namespace.
+ * This namespace handles utilities for determining the script environment and retrieving information about it.
+ * A word of caution: This namespace is considered an advanced API and might change without a new major version of the library.
+ *
+ * @namespace environment
+ */
+/**
+ * openHAB version
+ *
+ * @memberOf environment
+ * @name OPENHAB_VERSION
+ * @type {string}
+ */
+export const OPENHAB_VERSION: string;
+/**
+ * openHAB JavaScript library version
+ *
+ * @memberOf environment
+ * @name OPENHAB_JS_VERSION
+ * @type {string}
+ */
+export const OPENHAB_JS_VERSION: string;
+/**
+ * GraalJS version
+ * @memberOf environment
+ * @name GRAALJS_VERSION
+ * @type {string}
+ */
+export const GRAALJS_VERSION: string;
 //# sourceMappingURL=environment.d.ts.map

types/utils.d.ts

@@ -80,10 +80,10 @@ export function dumpObject(obj: any, dumpProps?: boolean): void;
 /**
  * openHAB JavaScript library version
  *
+ * @deprecated use {@link environment.OPENHAB_JS_VERSION} instead
  * @memberof utils
  * @name OPENHAB_JS_VERSION
  * @type {string}
  */
-declare const VERSION: string;
-export { VERSION as OPENHAB_JS_VERSION };
+export const OPENHAB_JS_VERSION: string;
 //# sourceMappingURL=utils.d.ts.map