Skip to content

TS7 JSDoc @overload is ignored on const arrow function (works in 6.0.2, not in 7.0.2)Β #65558

Open

Description

@abc-abc-ab

πŸ”Ž 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 | number

with 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 of const 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 function declaration (g in 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

  1. zhengdaodeguL commented on Nov 18, 2026

    @zhengdaodeguL

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions