Theo's Typesafe Cult•14mo ago

JSDoc - Functions Taking Never

I'm using JS + JSDoc + @ts-check in a project, and I'm running into the following somewhat odd issue. It appears that when using JSDoc, TypeScript fails to recognize that an argument of type never should not be passed at the call site. Here's the minimum code needed to recreate this issue:

/**
 * @param {never} _
 */
function test(_) {}
test();

/**
 * @param {never} _
 */
function test(_) {}
test();

Of course, in the actual codebase I'm dealing with, the never comes from a conditional type, but it's the same issue. Basically, my question is: What is going wrong here? Am I messing something up? Is this a bug in TypeScript? Is there anything I can do right now to fix this? Any help would be appreciated. Proof (screenshot of the diagnostic) is attached.

2 Replies

nekodjin•14mo ago

it works just fine if you use @type on the parameter instead of @param on the function, like this:

function test(/** @type {never} */ _) {}
test();

function test(/** @type {never} */ _) {}
test();

nekodjin•14mo ago

that leads me to believe that it's just a bug in TS, but it'd still be nice if anyone knows how to get around this issue without just using @type on the parameter

Gaming

Programming

JSDoc - Functions Taking Never