Decouple Action Names from Osee Communication IDs

Oct 13, 2025 by leolavanderia.com.br 49 views

Internal: Issues with Action IDs (and proposed solution)

Background

In our current implementation, Action IDs are defined as enums within each submodule, in the files <submodule>/actionId.ts. However, there are several issues with this approach that need to be addressed.

A Companion module defines actions by passing a JavaScript object to the method: setActionDefinitions(actions) where actions is an object:

{
  action1: <action1 description>,
  action2: <action2 description>,
  ...
}

In our repo, the file src/actions.ts asks each submodule to return an object containing its action descriptions. It then merges them into a single object using the spread operator ...:

return {
  ...MixEffectActions.create(),
  ...SuperSourceActions.create(),
}

which, at runtime, resolves to:

return {
  pgmIndex: {<pgmIndex action description>}
  pvwIndex: {<pvwIndex action description>}
  ...
  superSourceEnable: {<superSourceEnable action description>}
  superSourceSource: {<superSourceSource action description>}
  ...
}

Issues

Modularity: The local ActionId definitions give a false impression of modularity since the enum is local to the submodule. However, what is passed to Companion is an object whose property names are just the string values of the enums. For example, even though the definition in mixEffect/actions.ts starts with [ActionId.PgmIndex]: {...}, what is passed to Companion is pgmIndex: {...}.

Why this is a problem: Two submodules can validly define ActionIds with members having the same string value, but when merged, standard JavaScript behavior will keep only one of these properties. As a result, one of the action definitions simply won't show up in Companion, and there is essentially no clue in the code as to why the other one is missing.

Specific Example: the Quality command is used to change either recording quality or streaming quality (depending on its first arg). However, both Osee and we (Issue #107), believe that it would be more logical to group these two subcommands with their respective submodules (record, streaming). To do so, one could define enums as follows:

// in record/actionId.ts:
enum ActionId {
  ...
  RecordQuality = 'quality'
}

// in streaming/actionId.ts:
enum ActionId {
  ...
  StreamQuality = 'quality'
}

Since both enums evaluate to the same string, however, the object passed to Companion (before JavaScript merging) will look something like:

{
  quality: {<streamingQuality action description>}
  ...
  quality: {<recordQuality action description>}
}

which resolves to:

{
  quality: {<recordQuality action description>}
}

String Value Changes: Another issue arises if one changes the string value of an ActionId: it will break any existing user's actions that use the old string name even though nothing has changed in the "coding" portion, i.e. in <submodule>/actions.ts.

This is because Companion uses the string as the unique identifier for that action and it is the string, not the enum that is passed to Companion. Admittedly, it's unlikely that a developer would do so, especially considering the next issue, but actually, I'm going to recommend that we do change them all!

Dual Purpose: Finally, a more general issue: ActionId serves both as the Companion action identifier and the Osee communication protocol id string. I.e. it's used in sendCommand(ActionId.xxx, ...) in the actions' callbacks and in the update and sync functions defined in state.ts files.

Thus, if the communication protocol changes, either the actions have to be "broken" as in 2, in order to keep communication working or special exceptions have to be made. This ties in with issue #96, that the communication protocol needs to be decoupled from the Companion logic.

Looking back at the first issue in this list, one can see that the problem described there originates exactly because the ActionId is serving dual purpose.

Possible Solutions

Global ActionId File: One could require all ActionIds to be defined in a single global file. This would not prevent two entries resolving to the same string but it might make it less likely. Unfortunately, doing so also undoes the modularity achieved by splitting functions into separate subdirs. Also, this solution doesn't address decoupling.
Modular ActionId Names: A solution aiming for both modularity and decoupling would be to require all actionId string values to start with the module name.

2a. For example, an enum member might be: Quality="recordQuality" or "record_Quality". This would break every existing action, but that could be fixed with an upgrade script. Perhaps a v2.0 activity? but at the very least, all newly defined actions should conform to this convention.

2b. state.ts for each submodule would define a dictionary (map or object) mapping each ActionId to the communication id. (This follows along my proposal in #96, to make states the location to map internal representation to communication protocol values.) so for example, using an object:

const OseeID = {
  [ActionId.Record]: "record",
  [ActionId.Quality]: "quality",
}

or using a Map:

const OseeID = new Map([
  [ActionId.Record, "record"],
  [ActionId.Quality, "quality"],
])

(note this map/object is not exported: it is local to state.ts)

Now with this structure in place, the sendCommand lines are all moved from action.ts to state.ts, thus achieving a proper decoupling (i.e. actions, which are part of the presentation layer do not interact directly with the communication layers). In my proposed framework, state is defined as a class with methods for decoding, encoding, and providing the list of choices. In this framework, it makes sense for sendCommand to be part of the encoding function. For example:

class recordState {
  ...
  qualityChoices(protocolOrder = false): string[] {
    // return array of choices, depending on fw version
    // guarantee protocol ordering if protocolOrder is true
    return ["high", "medium", "low"]
  }
  encodeQuality(qualityVal: string): void {
    const qualityNum = this.qualityChoices(true).indexOf(qualityVal)
    //if (sendIt) {
      sendCommand(OseeID[ActionId.Quality], ReqType.Set, [0, qualityNum])
    //}
    //return {id: OseeID[ActionId.Quality], type: ReqType.Set, val: [0, qualityNum]}
  }
  decodeQuality(qualityNum: idx): string {
    // this should probably be a private function -- used in update()
    return this.qualityChoices(true)[idx]
  }
}

Conclusions

The current implementation of ActionId has issues which could be solved by
1. Decoupling action names from Osee communication ids using mapping-objects in states.ts
1. Requiring action names to be "modular", i.e. name starts with the module name.
2a. if this is relegated to v2.0, then at least all new actions should be named in this modular way.
Internal: Issues with Action IDs (and proposed solution) - Q&A

Q: What are the main issues with the current implementation of Action IDs?

A: The main issues with the current implementation of Action IDs are:

Modularity: The local ActionId definitions give a false impression of modularity since the enum is local to the submodule. However, what is passed to Companion is an object whose property names are just the string values of the enums.
String Value Changes: Another issue arises if one changes the string value of an ActionId: it will break any existing user's actions that use the old string name even though nothing has changed in the "coding" portion, i.e. in <submodule>/actions.ts.
Dual Purpose: ActionId serves both as the Companion action identifier and the Osee communication protocol id string.

Q: What is the proposed solution to address these issues?

A: The proposed solution is to:

Decouple Action Names from Osee Communication IDs: Use mapping-objects in states.ts to decouple action names from Osee communication IDs.
Require Modular ActionId Names: Require all actionId string values to start with the module name.

Q: Why is it necessary to require modular actionId names?

A: Requiring modular actionId names will prevent two entries from resolving to the same string, which can cause issues when merging action definitions. It will also make it easier to identify which action belongs to which module.

Q: How will the proposed solution affect existing actions?

A: The proposed solution will break existing actions that use the old string names. However, this can be fixed with an upgrade script. It is recommended to update all existing actions to conform to the new modular naming convention.

Q: What are the benefits of the proposed solution?

A: The proposed solution will:

Improve Modularity: By requiring modular actionId names, we can improve modularity and prevent issues caused by duplicate string values.
Decouple Action Names from Osee Communication IDs: By using mapping-objects in states.ts, we can decouple action names from Osee communication IDs, making it easier to maintain and update the code.

Q: How will the proposed solution affect the code structure?

A: The proposed solution will require changes to the code structure, specifically in the states.ts file. The sendCommand lines will be moved from action.ts to state.ts, and the ActionId enum will be replaced with a mapping-object.

Q: What is the recommended approach for implementing the proposed solution?

A: The recommended approach is to:

Update all existing actions to conform to the new modular naming convention.
Create a mapping-object in states.ts to decouple action names from Osee communication IDs.
Move the sendCommand lines from action.ts to state.ts.

By following these steps, we can ensure a smooth transition to the new implementation and take advantage of the benefits offered by the proposed solution.