I am trying to properly document a scenario that happens throughout out a program I am working in. I am unsure how to properly express the expected resolution of certain promises. Below is my attempt to mock what is happening.
There are certain api promises, outside the scope of the program that I am trying to document. I mentioned this because documenting the api methods is not an option, but rather the variable that contain the resolved values of those promises is where I'd like focus.
// simplified example
function apiMethod() {
const fail = 0;
const response = {
error: fail ? "error message" : undefined, // undef if no errors
success: fail ? undefined : [ // undef if errors present
{key01: "val01", key02: 1, key03: {"subKey01": [1, 2, 3]}},
{key01: "val03", key02: 2, key03: {"subKey01": [4, 5, 6]}}
]
};
return new Promise(resolve => setTimeout(() => resolve(response), 250));
}
(async () => {
/**
* @typedef {object} thing
* @property {string} key01
* @property {number} key02
* @property {{subKey02: string[]}} key03
*/
/**
* @type {Promise<{success: thing[]|undefined, error: string|undefined}>}
*/
const myVar = await apiMethod();
console.log(myVar.key01);
})();
This seems to work mostly well, but where I am getting stuck on is expressing that the success property could be undefined under certain circumstances. Right now this is how the vscode tooltip looks when hovering the myVar;
const myVar: Promise<{
success: thing[];
error: string | undefined;
}>
Note the missing undefined for success
This is how the vscode tooltip looks when hovering thing in the @type expression:
type thing = {
key01: string;
key02: number;
key03: {
subKey02: string[];
};
}
Questions:
Is is possible to express that
successwill be an array ofthingobjects or undefined? When usingtypedefit doesn't seem like I can do this.Right now it only seems possible to see the exploded view of the
thingobject when hoveringthingin the@typeexpression. When I hovermyVarit simply shows that success will be an array ofthings. Is it possible show this "exploded" view ofthingwhen hoveringmyVar, whilst still using@typedef?