Support union-like classes in projenrc.json

Union-like values are instances of classes that behave like unions in other languages. In TypeScript, the constructor is made private, and the only way to instantiate the class is by calling one of its static methods, each of which may represent a different kind of value or simply a different way to initialize the object.

Working backwards, we might imagine if a project’s constructor has an option that is typed as a union-like :

export class ReleaseTrigger {
  private constructor(options: ReleaseTriggerOptions = {}) {
    // ...
  }
  
  public static manual(options: ManualOptions) {
    return new ReleaseTrigger(...);
  }
  
  public static scheduled(options: ScheduledOptions) {
    return new ReleaseTrigger(...);
  }
}

Then the user should be able to configure it in their projenrc.json like this:

{
  ...
  releaseTrigger: {
    manual: {
      // manual options
      // these should decompose into
      // object/array/boolean/number/string/enum
    }
  }
  // or
  releaseTrigger: {
    scheduled: {
      // scheduled options
    }
  }
  

Open questions:

• Does jsii support union-like classes explicitly? What type information is provided / how easy is it to retrieve the information for the different options?
• What should happen if one of the methods expects a value that can’t be deconstructed? e.g. MyUnionLike.fromChoiceA(project: Project, props: ChoiceAOptions). Does this imply fromChoiceA will not be available for use in projenrc.json?
• ~How much extra effort is required to support union-likes for other projenrc types (e.g. projenrc.java)?~ Actually I think we already have this for free from jsii.

[eladb]

Does jsii support union-like classes explicitly? What type information is provided / how easy is it to retrieve the information for the different options?

No explicit support for union-like classes at the moment, but those types are jsii-compatible (just classes with a bunch of static methods).

What should happen if one of the methods expects a value that can’t be deconstructed

I think it implies it won’t be usable in JSON. I am wondering if we should prohibit such APIs (basically add a test that validates that all APIs are deconstructable).

How much extra effort is required to support union-likes for other projenrc types

Indeed, union-likes are compatible with JSII and can be used from all JSII languages. That’s part of the reason we used this pattern.

Prior art

• Union-like (aka enum-like) classes have been conceptualized in the AWS CDK guidelines.
• We dealt with this before in decdk. Here’s deconstructEnumLike().

I am wondering if we should vend a “declarative constructs” library that supports all of this once and can be used by all CDKs. A related capability is producing a JSON schema for these files (see https://github.com/projen/projen/issues/1017).

[github-actions[bot]]

This issue is now marked as stale because it hasn’t seen activity for a while. Add a comment or it will be closed soon. If you wish to exclude this issue from being marked as stale, add the “backlog” label.