Raise warning when type unions are used

[Chriscbr]

Describe the feature

Add a warning in jsii that warns users if they are using a type union in a public API. This might be obtrusive to those not expecting these new warnings, so there should be a simple mechanism to disable this entire type of warning from appearing. Alternatively, this warning could be opt-in.

There should also be a mechanism for suppressing individual cases of this warning, for cases where the type union is intentional. This could be achieved through some configuration in package.json, or more preferably, some way to annotate the code inline like adding "@jsii-ignore type-union" to the method's docstring.

Use Case

Type unions should usually be aoivded when writing APIs with jsii because jsii will translate this into an opaque "Object" for languages like Java C#, and Go. That said, it's not forbidden because they do still work, and are available for when alternatives are not possible. But new users writing code for jsii-based libraries may not know this, so they may unintentionally write this TypeScript code out of the box.

Proposed Solution

No response

Other Information

There is an RFC to provide a better user experience around type unions: aws/aws-cdk-rfcs#194. That would nullify the need for this feature -- but also, raising this warning might be a good short-term fix, especially if type aliases requires a breaking change / a new version of JSII.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

N/A

Environment details (OS name and version, etc.)

N/A