search

openhab / openhab-js

openHAB JavaScript Library for JavaScript Scripting Automation
https://www.openhab.org/addons/automation/jsscripting/
Eclipse Public License 2.0
38 stars 31 forks source link

HostRule is missing type definition #345

Open wertzui opened 3 months ago

wertzui commented 3 months ago

rules.JsRule({...}); returns a HostRule, but HostRule is only defined as object with a documentation link to https://www.openhab.org/javadoc/latest/org/openhab/core/automation/rule.

It would be good if the complete type for HostRule would be provided.

florian-h05 commented 3 months ago

IMO JSRule should rather return nothing, I don’t see a usecase where the return value is needed.

wertzui commented 3 months ago

My use case is that I want to get the generated UID after creating the rule.

florian-h05 commented 3 months ago

I would rather manually set the UID of the rule than getting it afterwards.

wertzui commented 3 months ago

And I would rather rely on the library to ensure valid and unique names 😉

florian-h05 commented 3 months ago

Those names are however „unpredictable“ which indeed is a problem when using the UI to manually trigger the rule.

The thing is, I don’t want do document the return value of JSRule because I don’t want to encourage users to use the returned object. Without having a translation layer from Java to JS, users are likely to run into type problems and I don’t want to maintain this additional code.

I would instead propose to have JSRule just return the UID of the created rule.

wertzui commented 3 months ago

Returning the UID would be fine for my use case, but it might not be for others.

What about writing a wrapper around the Java Rule interface, just as Item is a wrapper around the Java Item interface? That would probably break less peoples code, because the wrappers methods could still have the same names as the Java Rule interface.

florian-h05 commented 3 months ago

What about writing a wrapper around the Java Rule interface, just as Item is a wrapper around the Java Item interface?

As said above: I don’t want to maintain this additional code, which use case I consider fairly limited.

florian-h05 commented 3 months ago

The raw Java rule provides:

getActions: JSRules have only one action, and this is the execute callback. getConditions: JSRules don’t have conditions. getConfiguration: JSRule does not set configuration, nothing to get here. getConfigurationDescriptions: same as above getDescription: This is what you set as descriptions, instead of getting it afterwards memorise it. getModule: Gets a action/condition/trigger by id. See explanation above for them. getName: same as getDescription getTags: same as getDescription getTemplateUid: should not be set for JSRules. getTriggers: see above. getUid: only useful method. getVisibility: is always visible, method not useful.

So as you can see it is only the UID getter that is useful.