Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax

[DavidBruant]

🔎 Search Terms

jsdoc @import "is declared but its value is never read"

🕗 Version & Regression Information

I have seen this error since the introduction of @import in jsdoc comments (TS 5.5 if i recall correctly)

⏯ Playground Link

No response

💻 Code

I made a testcase repo https://github.com/DavidBruant/jsdoc-import-unused-testcase It is as reduced as a managed to make it

The code :

/** @import {ImportedType} from './types.d.ts' */

function id() { return undefined }

/** @type {Set<ImportedType>} */
export const phases = new Set(['a', 'b'])

The types.d.ts file:

export type ImportedType = 'a' | 'b'

🙁 Actual behavior

tsc and VSCodium both say:

code.js:1:5 - error TS6133: 'ImportedType' is declared but its value is never read.

1 /** @import {ImportedType} from './types.d.ts' */

🙂 Expected behavior

There shouldn't be an error because of the line using the type : /** @type {Set<ImportedType>} */

We've had this error in plently of places. It also seems like it occurs more regulary when the type is used within a generics

Additional information about the issue

For some reason, removing function id() { return undefined } from the code solves the problem while it seems completely unrelated to the problem

[Andarist]

Interestingly, I can't repro it using the bug workbench: workbench

[regseb]

I think I have the same problem.

• TypeScript reports that an import is useless when used in the return type of a function. bad.js 👎
• But it doesn't report a problem if it's used in the return type of two functions. good1.js 👍
• Or if used in the type of a variable good2.js 👍

---

• package.json

  {
    "name": "testcase",
    "version": "1.0.0",
    "type": "module",
    "dependencies": {
      "@types/node": "22.10.5",
      "playwright": "1.49.1",
      "typescript": "5.7.3"
    }
  }
  

• tsconfig.json

  {
    "compilerOptions": {
      "module": "nodenext",
      "noUnusedLocals": true,
      "noEmit": true,
      "checkJs": true
    }
  }
  

• bad.js

  /**
   * @import { Page } from "playwright"
   */
  
  /**
   * @returns {Page|undefined}
   */
  function foo() {
      return undefined;
  }
  
  console.log(foo());
  

• good1.js

  /**
   * @import { Page } from "playwright"
   */
  
  /**
   * @returns {Page|undefined}
   */
  function foo() {
      return undefined;
  }
  
  /**
   * @returns {Page|undefined}
   */
  function bar() {
      return undefined;
  }
  
  console.log(foo(), bar());
  

• good2.js

  /**
   * @import { Page } from "playwright"
   */
  
  /**
   * @type {Page|undefined}
   */
  let foo;
  
  console.log(foo);
  

1. npm install
2. npx tsc

   bad.js:2:4 - error TS6133: 'Page' is declared but its value is never read.
   
   2  * @import { Page } from "playwright"
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   
   
   Found 1 error in bad.js:2
   

[mantoni]

While we wait for the fix to be merged, here is a (surprising) workaround:

/**
 * @import { Page } from "playwright"
 */
'ignore';

// ...

[DavidBruant]

I see that TypeScript 5.8.3 has recently been released

When i compare 5.8.2 and 5.8.3, i can see the commit https://github.com/microsoft/TypeScript/commit/ee3dd7264b23e58bbad86d08a475cac78f330abf which was the result of merging https://github.com/microsoft/TypeScript/pull/60921 if i understand correctly

so i expected the bug described in this issue to be fixed

However, i did the reproduction steps in the testcase repo (i updated TS to 5.8.3) https://github.com/DavidBruant/jsdoc-import-unused-testcase and i can still see the same bug both in VSCodium (i checked the TS version being used in the bottom right corner) and tsc

I'm not sure where the problem is

Maybe i misunderstood the pull request or the content of the 5.8.3 release or the typescript release process or maybe what's available on npm is slightly different or something else?

If anyone sees this message, can you check whether the issue is fixed on your end, please? Thank you 🙏

[regseb]

If anyone sees this message, can you check whether the issue is fixed on your end, please? Thank you 🙏

I've tested my example https://github.com/microsoft/TypeScript/issues/60908#issuecomment-2585351519. I still get the error with TypeScript 5.8.3.

[DavidBruant]

I'd love to reopen this issue but don't have the permissions to

@jakebailey could you to reopen this issue, please?

[regseb]

I created a testcase in Bug Workbench: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEAEFsHsBMFcA2BTAXKAdnZHkA8AXAKBAhgRQCVkBnaReAgS2g3S1h32NPCwFUM8GslgAZaAGMAhohroCAJ3jISYcJIAWySQGsAUvNBKVRNRABmTFBmmQ0xgJ4AHWgDpYbgjSL5n0RQInV1ALaGhQAF5QGiUmDABzM3NwKxs7BzTkNwArH2AAKgKiUAKIJkh-QNAAb1Dw0ABfUMVoSFAAIjdgAhd3T28OkoLgM0Li0ohFZAJ4RQwaWrDoRuHRi3gMSWZWUAAjaUUACgBKWpLQS+nZ+c6DgC8OgG4iVaJJVjoUN0RoBKODscTicnkA

// @module: nodenext
// @moduleResolution: nodenext
// @noUnusedLocals: true
// @checkJs: true

// @filename: types.d.ts
export type foo = string


// @filename: file.js
/**
 * @import { foo } from "./types.d.ts"
 */

/**
 * @returns {foo}
 */
function bar() {
    return "baz";
}

console.log(bar());

'foo' is declared but its value is never read.

---

There is no error when:

• @module: nodenext and @moduleResolution: nodenext are removed: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&ts=5.8.3#code/PTAEA...o8tAA
• foo is used two times: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...Ep5AA
• foo is used in @type: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...EoDoA
• ; is added after import: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...zmMgA