How to type a JavaScript function with JSDoc + TypeScript?

Question

Update (2023)

I actually did a talk on how to get tsc + JSDoc that answers this question and a few more:

https://jswithtypes.com

And created a package to help with the tsconfig boilerplate:

https://npmjs.org/jswt
```
npx jswt init
```

Original Question

I'm trying to use tsc with plain, Vanilla JS and I'm stumped on how to declare the type a function.

It seems like it should be this simple:

/** @type PersonGreet */
person.greet = function greet(other) {
  return `Hello ${other.name}, my name is ${person.name}!`;
};

Edit: /** @type PersonGreet */ is correct. The current behavior is a bug in tsc. The selected answer below gives valid workarounds.

Reduced Test Case

Ignore the fact that someone may want to refactor this into using classes or prototypes or some such - it serves well as a demonstration of the problem.

Repo: https://github.com/BeyondCodeBootcamp/hello-tsc

"use strict";

/**
 * @typedef {Object} Person
 * @property {String} name
 * @property {PersonGreet} greet
 */

/**
 * @typedef {Function} PersonGreet
 * @param {Person} other
 * @returns {String}
 */

let Person = {};

/**
 * Creates a person
 * @param {Object} p
 * @param {String} p.name
 * @returns {Person}
 */
Person.create = function (p) {
  let person = {};

  person.name = p.name;

  /////////////////////////////////////////////////////////////////////////////////
  //
  // error TS7006: Parameter 'other' implicitly has an 'any' type.  <======= WRONG!
  //
  /////////////////////////////////////////////////////////////////////////////////

  /** @type PersonGreet */
  person.greet = function greet(other) {
    return `Hello ${other.name}, my name is ${person.name}!`;
  };

  return person;
};

module.exports = Person;

Incorrectly Typed as "any"

When I run tsc to check it gives an error about an implicit any:

tsc -p jsconfig.json

person.js:28:33 - error TS7006: Parameter 'other' implicitly has an 'any' type.

28   person.greet = function greet(other) {
                                   ~~~~~


Found 1 error in person.js:28

What to do?

To me this seems like a bug in tsc... but this is JS 101 stuff, surely there must be a way to type a function?

What annotation do I need to use to declare the function's type? Or can tsc / tsserver / typescript just not handle this kind of rudimentary use of JS?

Does this answer your question? Typescript: TS7006: Parameter 'xxx' implicitly has an 'any' type — EvanM
– EvanM, Commented Aug 9, 2022 at 2:08
I found a workaround: @typedef {(other: Person) => string} PersonGreet instead of just defining it as "Function" — qrsngky
– qrsngky, Commented Aug 9, 2022 at 3:05
@EvanM no. That's unrelated. This is about a declared type being misinterpreted as not declared due to being a function. — root-aj
– root-aj, Commented Aug 9, 2022 at 11:21
Best workaround @callback instead of @typedef {Function}. I've filed a bug with tsc: github.com/microsoft/TypeScript/issues/50274 — root-aj
– root-aj, Commented Aug 13, 2022 at 2:45
It feels like the underlying issue here was that Person should be a class with a .create` function that has accurate docs on it, using a normal new Person(name) instead of a faux static Person.create? No need for all those separate "unconnected" pieces of JSDoc that way. (Even if you also add a static create to the class, yielding a new Person instance). — Mike 'Pomax' Kamermans
– Mike 'Pomax' Kamermans, Commented Jan 2, 2024 at 19:17

lepsch · Accepted Answer · 2022-08-09 07:03:47Z

5

Solution 1

You should use @callback instead of @function like so:

"use strict";

/**
 * @typedef {Object} Person
 * @property {String} name
 * @property {PersonGreet} greet
 */

/**
 * @callback PersonGreet
 * @param {Person} other
 * @returns {String}
 */

let Person = {};

/**
 * Creates a person
 * @param {Object} p
 * @param {String} p.name
 * @returns {Person}
 */
Person.create = function (p) {
  let person = {};

  person.name = p.name;

  /** @type {PersonGreet} */
  person.greet = function greet(other) {
    return `Hello ${other.name}, my name is ${person.name}!`;
  };

  return person;
};

module.exports = Person;

Solution 2

Or, declare a @typedef using typescript syntax like the following:

/**
 * @typedef {(other: Person) => string} PersonGreet
 */

answered Aug 9, 2022 at 7:03

lepsch

10.5k5 gold badges33 silver badges48 bronze badges

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

1 Comment

root-aj Over a year ago

Side note: It seems that tsc doesn't recognize @function in any capacity, at all.

Collectives™ on Stack Overflow

How to type a JavaScript function with JSDoc + TypeScript?

Update (2023)

Original Question

Reduced Test Case

Incorrectly Typed as "any"

What to do?

1 Answer 1

Solution 1

Solution 2

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

Update (2023)

Original Question

Reduced Test Case

Incorrectly Typed as "any"

What to do?

1 Answer 1

Solution 1

Solution 2

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related