Allow actions to return result values for use in the next sequential action

[jswalden]

Is this a feature relevant to companion itself, and not a specific module?

• I believe this to be a feature for companion, and is not specific to a module

Is there an existing issue for this?

• I have searched for similiar existing issues

Describe the feature

I propose that we add a setResult(value: JsonValue | undefined) method to CompanionActionContext. The action callback can call this function to set a result value for the action. This result value then can be exposed to the next action -- or to multiple actions in a next action that's a concurrent action group, as a result might want to be consumed in several different ways at once (for example, a PTZ camera inquiry that returns an entire block of parameter values) -- using a $(this:result) variable. The result type can even be specified in InstanceTypes['actions'][K]['result'], narrowing from JsonValue. When the result is no longer needed, very likely after that next action, it gets GC'd.

I have a working implementation of all this, that behaves as desired with a test module that makes use of the new API.

(I was partly inspired my by own desire for this, partly inspired by another PTZ module having recently added a raft of variables and ongoing polling to fill them all -- when as ptzoptics-visca would use it I could instead trivially, and almost-directly, return the results of VISCA inquiries and then the user could decide what he wanted and at what times he wanted it.)

Usecases

Many devices/services/etc. include a query facility to return information to the user. A Companion module can expose the results of such a query to the user in two ways: by altering the actions/action options/etc. defined for the module, or by altering the variables defined (or their values) for the module.

Altering the actions/action options/etc. of the module is heavy-handed. To use query results, the user generally must resort to the Companion admin interface to make use of whatever is new.

Altering variables can work for some queries, when the information represents some kind of overall connection state, and every actor performing a query wants the same results. But for others, it breaks down.

Imagine a module representing a physical device generating cryptographically secure random numbers: you'd really want to return the value only to the use that wants it, not blast it to the world.

Or imagine a PTZ camera that you can perform inquiries of, to retrieve particular bits of information about it. You could create a polling loop and constantly update every piece of information in dedicated variable -- but that's overhead. You could create the variables, then offer actions to trigger updates to them -- but then you'd have to use a trigger to wait for the update, or you'd have to guarantee your action delayed til the result was saved (and woe betide the user who accidentally doesn't use a sequential action group).