[composable-controller] Better typing for state, messenger, strict type checks for inputs, remove #controllers field

[MajorLift]

Explanation

There are several issues with the current ComposableController implementation that should be addressed before further updates are made to the controller (e.g. #3627).

• Removes #controllers class field, which is not being updated by #updateChildController or anywhere else.
  • Removing this makes it clear that the list of child controllers to be composed is determined at class instantiation and cannot be altered later.
  • This behavior is consistent with #updateChildController being a private method.
• Types BaseController, ComposableController state with Record<string, Json>
  • Opted to use any to disable BaseController state type constraint, as there is no straightforward way to type BaseControllerV1 state to be compatible with Json.
• Adds a isBaseController type guard, and removes the deprecated subscribed property from BaseController.
• Removes ControllerList type in anticipation of [composable-controller] Make class and messenger generic upon child controllers #3627. Internally, ControllerInstance will be used to type child controllers or unions and tuples thereof.
• Adds BaseControllerV{1,2}Instance types.
• Populates state metadata object in constructor with child controllers.

References

• Blocks [composable-controller] Make class and messenger generic upon child controllers #3627
• Closes composable-controller: Replace use of any with proper types (non-test files only) #3716
  • Replaces some TODOs with comment explaining necessity of any usage.
• Closes [composable-controller] Fix incorrect #updateChildController behavior and improve typing #3907
• Should be released together with Bump min Node version to 18.18; use LTS for dev #3611 and not before.

Changelog

Recorded under "Unreleased" heading in CHANGELOG files.

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've highlighted breaking changes using the "BREAKING" category above as appropriate

[MajorLift]

Added json-rpc-engine as a TypeScript project reference (but not in the build tsconfig) instead of introducing it as a dependency, since it's only being used in a test file.

[mcmire]

Do we also want to add json-rpc-engine as a dev dependency? Maybe it makes no difference from a TypeScript perspective, but it communicates the dependency from a Yarn/NPM perspective.

[MajorLift]

Fixed here: 5da0893

Will a json-rpc-engine project reference need to be added to tsconfig.build.json as well?

[mcmire]

If it's only being used for tests, then you're correct, I don't think adding it to tsconfig.build.json would be needed. You should be able to test this by running yarn build — you shouldn't see any errors.

[MajorLift]

No errors on yarn build! Think we're good to go.

[MajorLift]

Previous typing of ControllerInstance['state'] implicitly evaluated as any.

This is the error if any is replaced with something wider than Json e.g. unknown:

Type 'ComposableControllerState' does not satisfy the constraint 'Record<string, Json>'.
  'string' index signatures are incompatible.
    Type 'Record<string, unknown>' is not assignable to type 'Json'.

[MajorLift]

Ideally, this would be something that covers the state types of both BaseController versions:

Record<string, BaseState & Record<string, unknown> | Record<string, Json>>

But this results in an implicit any error, and it conflicts with the messenger typing for allowed events. Using unknown currently seems to be the best option.

To be revisited once AllowedEvents is narrowed by #3627.

[MajorLift]

No reason to keep this as string since ComposableController doesn't use any actions from other controllers.

[MajorLift]

Test case added for this branch.

[MajorLift]

Since the child controller is validated as BaseControllerV2, its state type is guaranteed to be Record<string, Json>. It's therefore safe to narrow childState from Record<string, unknown>.

[MajorLift]

Added redundant property checks for extra runtime safety.

[MajorLift]

The BaseControllerV1 childState in #updateChildController is correctly inferred to BaseState & Record<string, unknown>.

[MajorLift]

Alternatively, we could keep the #controllers field and add something like the following to #updateChildController.

if (!this.state[name]) {
  this.#controllers.push(controller)
}

I prefer removing the field because it makes it unambiguous that child controllers aren't meant to be added, and their state and subscriptions aren't meant to be mutated after instantiation.

Also, having ComposableController depend on mutable internal state would introduce complications for #3627.

[mcmire]

Looks good!