feat!: api 2.0

[Julusian]

I don't know when 2.0 of this api will happen (maybe companion 4.1?), this is some changes that should be included in that release

It needs some further testing, but the change to esm should have no impact for modules due to require(esm) support being enabled by default since 22.12

TODO:

• decide on and include RFC: Reduce controlId awareness from modules #141
• decide whether to remove advanced-feedbacks
• check for anything else
• rework the apis for udphelper/tcphelper to make them safer to use. currently they return promises which are typically not awaited and so can crash modules [BUG] Unresolved host for udp.send() causes unhandled exception. #146
• consider removing the ipc wrapping from this repository
  I have been playing with this in the https://github.com/bitfocus/companion-surface-base api. This moves us to be a little more like 2.x, with the main file being a class export. And leaves the ipc wrapping to be the responsibility of Companion. Which means that we have scope to easily inject code into the modules, and avoid baking some code into every module which may be better to be provided by companion.
  If we had this, then we could more easily decide to leave certain operations to be done inside the module thread, and minimise the penalty of ipc. doing that today is hard because we need to handle old modules too

---

Release notes drafting:

• Replace runEntrypoint with a export default class ... (and export const UpgradeScripts = [])
• Drop node 18
• Lib is now ESM. shouldnt impact modules, typescript users may need a tweak to moduleResolution?
• UpgradeScripts now report for each option whether it is an expression or a value; this will break existing scripts
• parseVariablesInString has been removed, this is run for you for any text fields which have useVariables set. And for anything in expression mode.
• Users should rework their actions+feedbacks to remove any unnecessary duplicates, now that any field can have variables
• Remove old 'isVisible' functions. 'isVisibleExpression' must now be used
• New logging utils, allows for creating scoped loggers not attached to your instance class
• Typescript: new constraint on config and secrets objects, to ensure they are json safe
• Typescript: Replace InputValue with JsonValue

[krocheck]

Forgive me.

I'm not at first glance seeing why this constitutes a v2 API, which might/probably has breaking changes. There's no changes to call/interface that I can see. What constitutes this being a v2 and what impact that does that have future/current to modules on a v1 API for those versions with regards to core releases?

[Julusian]

Currently none of this needs to be v2, but I think is a bit risky to do before v2 so am holding these changes until we are doing a v2.

I am anticipating that a v2 may happen as part of the graphics overhaul or 'extending expressions to action options', so want this to be ready for whenever they are.

I am expecting that we will have no difficulty supporting both v1 and v2 in companion, itll just need some separate implementation of some chunk of code to support both.

[dnmeid]

I am anticipating that a v2 may happen as part of the graphics overhaul or 'extending expressions to action options'

Currently my hope is that neither of these will make a breaking change necessary. For the expressions I see mainly a challenge with the upgade script, but that will greatly depend on the implementation route we take.
For the Graphics overhaul there will be a lot of new functionality but I think it should be possible to have all of that with a backwards compatibility.

[Julusian]

I am expecting that the expressions will 'break' any existing upgrade scripts, but I am happy to be proven wrong.

I am wondering if we should call it 2.0 even if there aren't any breaking changes, simply as a indicator to module devs that there is a significant amount of new stuff that they should incorporate.
At the very least, many should be reviewing their actions&feedbacks and merging the ones like do X and do X from variables, because this is going to be confusing UX.

And we might want to encourage (but not require) updating to whatever new preset structure we define.

We did briefly discuss replacing the current 'advanced' feedback type with something new, that would definitely be a breaking change, and maybe will land as part of the overhaul (I still need to begin thinking about how those will integrate to the new system, I suspect it will be some bad UX)

But again, none of this is set in stone, so this is simply some things I want to be in 2.0 whenever that happens.

[krocheck]

This all makes sense to me. Obviously what I'm about to say changes timelines, but I feel like a v2 API would be good to rollout at v4 Companion ... breaking or no. Point being, I think it will be confusing to roll that stuff in at a v4.1 and add v2 API then. I might be overthinking that, but its hard to tell how people are going to react to versioning in the v4 landscape with the store and live updates.