Model-View Controller (MVC) is the foundational pattern of PhET sims. "Property" is the foundation of PhET's MVC implementation. "Property" needs to be revisted, and likely revised.
The current Property hierachy was not designed, it has emerged. It is complex, and has gotten even more complex (and problematic) with PhET's switch to TypeScript. It's so complex that I don't have a complete picture of it in my head. That limits my ability to make daily decisions about assigning correct types to things, as well as making recommendations about how to generally improve things.
... Most of the confusion that I see in APIs tends to be related to the "Property" hierachy ...
Form a subteam, identify the lead.
Identify the classes, type aliases, etc. involved in the current implementation. Draw a diagram of how they relate (hierarchy and composition). Share this with the dev team.
Enumerate problems with the current implementation. Proritize. Identify what to address through type-checking, what to address via assertions, etc.
Design a better Property hierarchy. Draw a new diagram. Share with the team for discussion. Iterate on the design.
Implement the new design.
This will be a big piece of work, definitely a quarterly epic.
Model-View Controller (MVC) is the foundational pattern of PhET sims. "Property" is the foundation of PhET's MVC implementation. "Property" needs to be revisted, and likely revised.
The current Property hierachy was not designed, it has emerged. It is complex, and has gotten even more complex (and problematic) with PhET's switch to TypeScript. It's so complex that I don't have a complete picture of it in my head. That limits my ability to make daily decisions about assigning correct types to things, as well as making recommendations about how to generally improve things.
Based on conversations and meetings, I suspect that it's also confusing to other developers. In https://github.com/phetsims/chipper/issues/1281#issuecomment-1185933099 (Notes on bringing TS code up to the current standards) I said:
This will be a big piece of work, definitely a quarterly epic.