Typescript Convention: How to support PhET's option pattern?

[zepumph]

Linked issues:
phetsims/chipper#1049
phetsims/ratio-and-proportion#405
phetsims/ratio-and-proportion#404

@samreid and I spent the last couple hours preparing an extensive example of the ways that options are used throughout the project. We will commit this to a class in Wilder, which currently is passing the ts compiler. From here we can bring this to a group meeting to understand some of the constraints, and potential changes.

In general this felt stable enough that I will take the pattern for a test drive in RAP over in phetsims/ratio-and-proportion#404.

[zepumph]

@samreid how would you like to proceed?

[zepumph]

• Another question. For maintainability, it seems like every common code type should export a custom named options object even if there aren't any options defined by that type. Otherwise subtypes would just the type's supertype options. For example:

Node
Button
RoundButton

If button didn't define any new options, we wouldn't want RoundButton saying that it's options extend NodeOptions, because then if Button adds an option, you would have to change all usage sites. Thus I can imagine this line of code being used in this case;

type ButtonOptions = {} & NodeOptions;

// or maybe this?
type ButtonOptions = NodeOptions;

[zepumph]

I realized that in all the examples we had, everything was a required argument, so I added a subtype that actually supports "options", in the optional sense. @samreid will you please take a look, perhaps we should meet up to discuss these TODOs, but I was surprised that I didn't need to pass in a required argument to the supertype, perhaps I missed something stupid, or didn't use the right Types.

[zepumph]

I'm really happy about this pattern too, similar, but a bit different. It basically is just supporting (5) and (1) from https://github.com/phetsims/wilder/blob/eebf6c69eb068e06f6b5704744b40fc94b2879c0/js/wilder/model/WilderOptionsTypescriptTestModel.ts#L16-L28

Index: js/common/view/RAPTickMarkLabelsNode.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/js/common/view/RAPTickMarkLabelsNode.ts b/js/common/view/RAPTickMarkLabelsNode.ts
--- a/js/common/view/RAPTickMarkLabelsNode.ts	(revision b321fb1d02d5a131233efb3d94cf5fc2c596fdb1)
+++ b/js/common/view/RAPTickMarkLabelsNode.ts	(date 1635194641823)
@@ -32,11 +32,7 @@
    * @param {Object} [options]
    */
   constructor( tickMarkViewProperty: Property<TickMarkViewType>, tickMarkRangeProperty: Property<number>, height: number,
-               colorProperty: Property<Color | string>, options?: any ) {
-
-    if ( options ) {
-      assert && assert( !options.hasOwnProperty( 'children' ), 'RAPTickMarkLabelsNode sets its own children' );
-    }
+               colorProperty: Property<Color | string>, options?: Omit<NodeOptions, 'children'> ) {
 
     super();
 

[samreid]

Here's a stackoverflow on how to do xor values:

https://stackoverflow.com/questions/44425344/typescript-interface-with-xor-barstring-xor-cannumber

type IFoo = {
  bar: string; can?: never
} | {
    bar?: never; can: number
  };


let val0: IFoo = { bar: "hello" } // OK only bar
let val1: IFoo = { can: 22 } // OK only can
let val2: IFoo = { bar: "hello",  can: 22 } // Error foo and can
let val3: IFoo = {  } // Error neither foo or can

[zepumph]

We discussed this during dev meeting today. @samreid and I got good feedback. I would consider this wilder type our current convention. I made updates and added a TODO in regards to #128. There are now 7 TODOs for this in that file.

[samreid]

As I've tried to apply this pattern in Gravity and Orbits and Bending Light, I'm finding in some cases I need to invert the pattern a bit like so:

type BendingLightScreenViewImplementationOptions = {
  occlusionHandler?: () => void,
  horizontalPlayAreaOffset?: number,
  verticalPlayAreaOffset?: number,
  clampDragAngle?: ( angle: number ) => number,
  ccwArrowNotAtMax?: () => boolean,
  clockwiseArrowNotAtMax?: () => boolean
};

type BendingLightScreenViewOptions = BendingLightScreenViewImplementationOptions & PhetioObjectOptions;

abstract class BendingLightScreenView extends ScreenView {
  //...

  /**
   * @param {BendingLightModel} bendingLightModel - main model of the simulations
   * @param {boolean} laserHasKnob - laser image
   * @param {Object} [providedOptions]
   */
  constructor( bendingLightModel: BendingLightModel, laserHasKnob: boolean, providedOptions?: Partial<BendingLightScreenViewOptions> ) {

    const options = merge( {
      occlusionHandler: () => {}, // {function} moves objects out from behind a control panel if dropped there
      ccwArrowNotAtMax: () => true, // {function} shows whether laser at min angle
      clockwiseArrowNotAtMax: () => true, // {function} shows whether laser at max angle, In prisms tab
      // laser node can rotate 360 degrees.so arrows showing all the times when laser node rotate
      clampDragAngle: ( angle: number ) => angle, // {function} function that limits the angle of laser to its bounds
      horizontalPlayAreaOffset: 0, // {number} in stage coordinates, how far to shift the play area horizontally
      verticalPlayAreaOffset: 0 // {number} in stage coordinates, how far to shift the play area vertically.  In the
                                // prisms screen, it is shifted up a bit to center the play area above the south control panel
}, providedOptions ) as Required<BendingLightScreenViewImplementationOptions & Pick<PhetioObjectOptions, 'tandem'>>;

That is, provide a "type-specific" set of options, which often is the same as "these values can be used in the constructor".