Repository navigation
Description
π Search Terms
JSDoc, overload, TS7
π Version & Regression Information
- This changed between versions 6.0.3 and 7.0.2
β― Playground Link
No response
π» Code
main.js:
#!/usr/bin/env node
/**
* @overload
* @param {"a"} x
* @returns {string}
*/
/**
* @overload
* @param {"b"} x
* @returns {number}
*/
/**
* @param {"a" | "b"} x
* @returns {string | number}
*/
const f = x => {
if (x === "a") return "100";
else if (x === "b") return 10;
return x;
}
/**
* @overload
* @param {"a"} x
* @returns {string}
*/
/**
* @overload
* @param {"b"} x
* @returns {number}
*/
/**
* @param {"a" | "b"} x
* @returns {string | number}
*/
function g(x) {
if (x === "a") return "100";
else if (x === "b") return 10;
return x;
}
console.log(parseInt(f("a"), 10));
console.log(parseInt(g("a"), 10));tsconfig.json:
{
"compilerOptions": {
"rootDir": ".",
"module": "EsNext",
"target": "ES2025",
"strict": true,
"noEmit": true,
"allowJs": true,
"checkJs": true,
}
}
package.json:
{
"devDependencies": {
"typescript6": "npm:typescript@6.0.3",
"typescript7": "npm:typescript@7.0.2"
}
}
π Actual behavior
With TypeScript 7.0.2, the JSDoc @overload tags on a const arrow function are ignored. The function is typed from its implementation signature instead, so f("a") returns string | number rather than string.
Hovering f in tsserver shows:
const f: (x: "a" | "b") => string | numberwith no (+1 overload) suffix. As a result, parseInt(f("a"), 10) fails:
error TS2345: Argument of type 'string | number' is not assignable to parameter of type 'string'.
Type 'number' is not assignable to type 'string'.
This is wrong because:
- The identical overloads work in TypeScript 6.0.3 (no error).
- The identical overloads work in 7.0.2 when declared with
function g(x) {}instead ofconst f = x => {}.
π Expected behavior
@overload tags should be recognized on a const arrow function, the same way as in TypeScript 6.0.2.
Hovering f should show the overload signatures:
const f: {
(x: "a"): string;
(x: "b"): number;
}so f("a") returns string and parseInt(f("a"), 10) type-checks without errors.
This is expected because:
- The same code produces the type above in TypeScript 6.0.2.
- The same overloads on a
functiondeclaration (gin the example) already work in 7.0.2, so the declaration form alone should not change the result.
Additional information about the issue
Versions
- typescript 6.0.3: no error
- typescript 7.0.2: error on the
f("a")line only - Node: v26.9.0
- OS: Windows 11 26H2
Environment
Reproduced in a clean Docker container:
FROM node:26-slim
WORKDIR /app
COPY package*.json .
RUN npm i
COPY . .
CMD ["sh", "run.sh"]
- Image: node:26-slim (Node v26.13.1)
- typescript 6.0.3: no error
- typescript 7.0.2: error on the
f("a")line only
Workaround
Declaring the function with function f(x) {} instead of const f = x => {} makes the overloads work in 7.0.2.
Activity
zhengdaodeguL commentedon Nov 18, 2026
I would like to work on this regression. Could a maintainer please assign a milestone to this issue? The TypeScript contributing guide notes that PRs for issues without an assigned milestone are automatically closed, so I want to make sure the milestone is set before I open a PR.