Having reviewed the docs it my understanding that JSII/JSII-Docgen de-sugars type aliases are de-sugared, this is a perfectly understandable design decision.
However I've come across a bit of a quirky behaviour as described below, and as is viewable in the minimum reproducible example repo I created.
/**
* Interface for providing config for paramOne
*/
export interface IOne {
/**
* Param foo
*/
readonly foo: string
}
/**
* Declared type to wrap two options user can provide for the param
*/
export type ParamType = string | IOne
/**
* Function parameters
*/
export interface FunctionParams {
readonly paramOne: ParamType[]
}
export class ConstructFoo {
readonly internalParam: ParamType[]
constructor(fnParams: FunctionParams) {
this.internalParam = fnParams.paramOne
}
}As you can see, I am declaring parameter paramOne to expect an array of objects, I am not explicitly stating the type of the array as would be the case if I declared string[] | IOne[], thus from a TypeScript perspective, it will allow users to pass a mixed array of strings and objects matching interface IOne, as is shown to be working in my example invocation.
Current Behaviour
However the docs come out as
```typescript
public readonly paramOne: string | IOne[];
```
Which implies only the second type in the union can be an array, if a user were to attempt to use this as described in the docs they would get invalid code.
const arrayParams : ParamType[] = [ // ✅ Valid TypeScript Code
{
foo: 'bar'
},
'foobar'
]
const asDocsDescribe: string | IOne[] = [ // 🚨 Not valid code!
{
foo: 'bar'
},
'foobar'
]I believe this is an unintended consequence of the de-sugaring you are performing, and may require remediation?
Expected behaviour
Docgen should produce doc declaration for type paramOne as follows
```typescript
public readonly paramOne: string[] | IOne[];
```
Background
I am using this in a way where I want objects of interface IOne or strings in the interface, not both. I had declared my code as such as I found there were more optimal type guards available to me when I did it this way vs having string[] | IOne[]
Having reviewed the docs it my understanding that JSII/JSII-Docgen de-sugars type aliases are de-sugared, this is a perfectly understandable design decision.
However I've come across a bit of a quirky behaviour as described below, and as is viewable in the minimum reproducible example repo I created.
As you can see, I am declaring parameter
paramOneto expect an array of objects, I am not explicitly stating the type of the array as would be the case if I declaredstring[] | IOne[], thus from a TypeScript perspective, it will allow users to pass a mixed array of strings and objects matching interfaceIOne, as is shown to be working in my example invocation.Current Behaviour
However the docs come out as
Which implies only the second type in the union can be an array, if a user were to attempt to use this as described in the docs they would get invalid code.
I believe this is an unintended consequence of the de-sugaring you are performing, and may require remediation?
Expected behaviour
Docgen should produce doc declaration for type paramOne as follows
Background
I am using this in a way where I want objects of interface
IOneor strings in the interface, not both. I had declared my code as such as I found there were more optimal type guards available to me when I did it this way vs havingstring[] | IOne[]