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;
}>
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
success
will be an array ofthing
objects or undefined? When usingtypedef
it doesn’t seem like I can do this. -
Right now it only seems possible to see the exploded view of the
thing
object when hoveringthing
in the@type
expression. When I hovermyVar
it simply shows that success will be an array ofthing
s. Is it possible show this “exploded” view ofthing
when hoveringmyVar
, whilst still using@typedef
?