how to use interfaces with jsdoc?

Question

/**
 * @param {Object[]} items - Payload should be an array or objects which includes name property
 * @return {String[]} Returns names of all objects in that array
 *
 */

const namesOfItems = (items) => {
  return items.map((item) => item.name)
}

I have code like this. It accepts an param named items. Items should be any array of objects like user, car, company, country etc. if that object has a name property in it. Currently I'm using jsdoc in a project and I setted @param decorator as @param {Object[]} items however that declaration is not checking if that Object has a name property in it or not. In typescript there were interface's to handle that but I wonder how can I set my @param and show that it only accepts a Object with name property.

Looking for a solution like that below:

@param {Array<AnObjectWhichHasName>}

Answer 1

Typescript doesn't support defining interfaces via JSDoc. But you can use an object type in your @param:

/**
 * @param {{name: string}[]} items
 */
const namesOfItems = (items) => {
  return items.map((item) => item.name)
}

Or define the object type with @typedef and then use it:

/**
 * @typedef {{name: string}} AnObjectWhichHasName
 */

/**
 * @param {AnObjectWhichHasName[]} items
 */
const namesOfItems = (items) => {
  return items.map((item) => item.name)
}

Or use this alternative syntax for defining an object type:

/**
 * @typedef {Object} AnObjectWhichHasName
 * @property {string} AnObjectWhichHasName.name
 */

/**
 * @param {AnObjectWhichHasName[]} items
 */
const namesOfItems = (items) => {
  return items.map((item) => item.name)
}