JSDoc overloaded function not working with TypeScript

Question

I am using the JSDoc overload syntax as suggested in other questions and online, not sure if I have it correctly, but here goes:

/**
 * @param {string} param
 * @returns {'string result'}
 *//**
* @param {number} param
* @returns {'number result'}
*/
function overloaded(param) {
  switch (typeof param) {
    case 'string': return 'string result';
    case 'number': return 'number result';
  }

  throw new Error(`Invalid type: ${typeof param}`);
}

overloaded('seven');
overloaded(7);

This function should return string result exactly if the type of the input parameter is string and it should return number result exactly if the type of the input parameter is number. In normal TypeScript this would be:

function overloaded2(param: string): 'string result';
function overloaded2(param: number): 'number result';
function overloaded2(param: string | number): 'string result' | 'number result' {
switch (typeof param) {
    case 'string': return 'string result';
    case 'number': return 'number result';
}

throw new Error(`Invalid type: ${typeof param}`);
}

overloaded2('seven');
overloaded2(7);

The problem is that the JSDoc as I have it is probably incorrect because TypeScript inference as provided by the VS Code language service fails to pick up the overload:

Basically it only sees the first overload. Is the JSDoc support in TypeScript advanced enough for me to be able to type the JavaScript code to the same degree as the TypeScript counterpart? How would that look?

I suspect it's a vscode issue and not directly related to typescript or jsdoc? I was not able to get this to work reasonably and consistently either. Trying to document overloaded functions is a mess and if you add interfaces to the mix, it gets even more confusing. Have you tried generating actual documentation from these with jsdoc and see if you get better results? — danielv
– danielv, Commented Feb 21, 2019 at 18:55

Tomasz Lenarcik · Accepted Answer · 2023-02-19 19:30:33Z

1

TypeScript 5 will have a new @overload tag which will will allow you to do this:

/**
 * @overload
 * @param {string} param
 * @returns {'string result'}
 *
 * @overload
 * @param {number} param
 * @returns {'number result'}
 *
 * @param {string | number}
 */
function overloaded(param) {
  // ...
}

Check out this blog post for more details:

https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#overload-support-in-jsdoc

answered Feb 19, 2023 at 19:30

Tomasz Lenarcik

4,92021 silver badges31 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Miguel Sánchez Villafán Over a year ago

This is not working for me, TS only sees the last declaration any idea as to why?

Tomasz Lenarcik Over a year ago

@MiguelSánchezVillafán Its hard to say without seeing your code snippet.

JakeDK · Accepted Answer · 2022-03-28 13:52:48Z

1

UPDATE: Included my preferred method

/**
 * @callback ConvertNumberToArray
 * @param {number} input
 * @return {number[]}
 *
 * @callback keepStrings
 * @param {string} input
 * @return {string}
 */

/**
 * @type {ConvertNumberToArray & keepStrings}
 */
const parse = input => {
  if (typeof input === 'number') return [input]
  else return input
}

What it looks like in VSCode

ORIGINAL POST: Have a look here https://austingil.com/typescript-function-overloads-with-jsdoc/

Example

/**
 * @type {{
 * (input: number) => number;
 * (input: string) => string;
 * }}
 */
const double = (input) => {
  if (typeof input === 'number') {
    return input * 2
  }
  return input + input
}

edited Mar 28, 2022 at 13:52

answered Mar 15, 2022 at 19:53

JakeDK

1,2741 gold badge13 silver badges20 bronze badges

Collectives™ on Stack Overflow

JSDoc overloaded function not working with TypeScript

2 Answers 2

2 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related