[jsscripting] with jsscripting addon installed, scripts are missing variables defined in default preset

[ssalonen]

jsscripting addon is missing variables (for example itemRegistry) defined in the default JSR223 preset, as documented in https://www.openhab.org/docs/configuration/jsr223.html#default-preset-importpreset-not-required

Discussed also in community: https://community.openhab.org/t/all-my-ecmascript-scripts-stopped-working-throwing-exceptions/125341/7

Expected Behavior

jsscripting ECMAScript 2021+ scripts/rules should have the same built-in variables defined as JSR223.

Current Behavior

jsscripting ECMAScript 2021+ scripts/rules do not seem to have any(?) of the default variables defined. E.g. itemRegistry will cause a ReferenceError error.

Steps to Reproduce (for Bugs)

1. Follow steps 1-14 in [jsscripting] jsscripting automation bundle installation issues #11219. Expecting that we would not get ReferenceError with the new javascript engine

Context

Trying to migrate to ES6 in rules/scripts.

Your Environment

I can reproduce with 3.1.0 release and 3.2.0 M2.

Linux  5.13.13-200.fc34.x86_64 #1 SMP Thu Aug 26 17:06:39 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/all-my-ecmascript-scripts-stopped-working-throwing-exceptions/125341/10

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/usage-of-new-ecma2021-automation-scripting-graalvm/122724/24

[ssalonen]

@jpg0 commented the following

This is expected behaviour; if you want access to the item registry it must be imported, there are not magic predefined symbols like in the old runtime.

Question remains: why there are no "magic predefined symbols" defined?

After all, they are there to reduce the boiler plate needed for common operations and activities in rules and scripts?

[jpg0]

This behaviour is by-design, so as not to pollute the global namespace. Instead these things need to be imported, e.g.:

const { itemRegistry } = require('@runtime')

Happy to consider any suggestions on how to better support this, but I've switched from implicit to explicit to prevent accidental naming clashes, especially regarding usage of 3rd party libraries.

To go into more detail: when I was porting the old JS helper libraries to ES6, by far the most problematic areas were these predefined symbols. Often they would clash with some variable name, and some very weird and hard-to-debug error would arise. Trying to use 3rd party libraries (of which I now use extensively) was even worse, as you cannot change their internal names (and hey, things like event are pretty common!). I concluded that this mechanism was incompatible with 3rd party library support - and really with standard JS entirely (I know of no other JS runtime that does this). My solution was as above: make importation explicit (and as simple as possible - e.g. the Default namespace requires no package within the @runtime).

Saying this, I have not really looked deeply into trying to support this as a migration step, or for those who don't ever want to use 3rd party code. TBH I'm not a fan of making it a first-class feature as it would split script compatibility, but I have nothing against some kind of explicit migration shim.

It may be possible to achieve with a JS module that you always include that expands the default symbols into the global namespace, like:

module.exports = function() {
  Object.assign(global, require('@runtime'));
}();

But I have not tried this.

[ssalonen]

require('@runtime') looks very neat and makes access to the openhab utilities very easy.

Does that work out of the box with jsscripting? (I am a bit confused what comes with ohj and ohj-support)

[jpg0]

Yes, that should work out of the box.

ohj is essentially my replacement for the JS helper libraries, and ohj-support are a few bits that are required in Java to support it. Neither should be required.

[florian-h05]

@ssalonen You should have a look at openhab-js, which is included in the JS Scripting Binding and is the preferred way of interacting with openHAB:

This library aims to be a fairly high-level ES6 library to support automation in openHAB. It provides convenient access to common openHAB functionality within rules including items, things, actions, logging and more.

If that helps, you may close that issue.

[ssalonen]

Thanks @florian-h05 . The openhab-js library is certainly very welcome addition (was not documented / existing when I posted this issue, I believe). I am not sure it "solves" this specific issue, let me explain...

Also the (undocumented?) @runtime import is key to having built-ins such as ON, UNDEF etc.

This issue was risen by mismatch of expectations: I originally expected that jsscripting would allow me to write modern javascript using the same APIs available in older bundled-by-default javascript (nashorn engine). As discussed above, this is not the case and one can argue it is by design. I find the documentation omitting these aspects of the addon.

I would contribute some documentation myself, e.g. mentioning @runtime, however I am not sure what does it really contain... Is it all in "default preset" of JSR223? See docs

[florian-h05]

Hello @ssalonen,

Also the (undocumented?) @runtime import is key to having built-ins such as ON, UNDEF etc.

See DefaultScriptScopeProvider.java at the bottom of my post.

I would contribute some documentation myself, e.g. mentioning @runtime

That would be nice 👍, I think the best place for that would be the openhab-js README (this one should be copied to the JS Scripting README before a new openHAB Release as well as a new library version would be published).
I would add a note that advanced users could also use @runtime to the part where it says that openHAB-js is included by default in the JS Scripting binding and link to the @runtime section at at the bottom of the whole README.

What do you think of that @digitaldan?

however I am not sure what does it really contain... Is it all in "default preset" of JSR223?

Seems like everything in the JSR Docs is included (in DefaultScriptScopeProvider.java), but as I can see in SharedCache.java / jsscripting addon any addon could possibly add stuff to the scriptExtension.
The scriptExtension is made available as @runtime in JS Scripting by the ScriptExtensionModuleProvider.java.

When you look in openhab-js where @runtime is used (https://github.com/openhab/openhab-js/search?q=runtime), you can find some examples.

When you find all classes that implement the ScriptExtensionProvider you should find out what is included, of course that’s way too much. I would only have a look at the most important stuff.

[ssalonen]

@florian-h05 Improved documentation in openhab/openhab-js#110

[florian-h05]

@ssalonen Closing as the docs have been improved to document the JSR223 API.

Feel free to reopen if your problem is not solved.