How do I type a callback parameter in JSDoc?

The short answer

Name the callback’s type with @callback, listing its parameters and return type like a function’s, and use that name in the @param tag. For a small callback, an inline arrow type does the same job:

/**
 * @typedef {object} Order
 * @property {string} id
 * @property {number} total
 */

/**
 * @callback OrderTest
 * @param {Order} order
 * @param {number} index
 * @returns {boolean}
 */

/**
 * @param {Order[]} orders
 * @param {OrderTest} keep
 * @returns {Order[]}
 */
export function pickOrders(orders, keep) {
  return orders.filter(keep);
}

/**
 * @param {Order[]} orders
 * @param {(order: Order) => void} onEach
 */
export function forEachOrder(orders, onEach) {
  for (const order of orders) onEach(order);
}

const orders = [
  { id: "A-1001", total: 40 },
  { id: "A-1002", total: 12 },
];
pickOrders(orders, (order) => order.total > 25);
forEachOrder(orders, (order) => console.log(order.id));

export interface Order {
  id: string;
  total: number;
}

type OrderTest = (order: Order, index: number) => boolean;

export function pickOrders(orders: Order[], keep: OrderTest): Order[] {
  return orders.filter(keep);
}

export function forEachOrder(orders: Order[], onEach: (order: Order) => void): void {
  for (const order of orders) onEach(order);
}

const orders = [
  { id: "A-1001", total: 40 },
  { id: "A-1002", total: 12 },
];
pickOrders(orders, (order) => order.total > 25);
forEachOrder(orders, (order) => console.log(order.id));

The arrow functions passed to pickOrders and forEachOrder need no JSDoc of their own: order is an Order because the parameter’s type says so.

Why it works

@callback OrderTest declares a function type, the same as @typedef {(order: Order, index: number) => boolean} OrderTest, but with room for a description on every line. When a function literal is passed where that type is expected, TypeScript types its parameters from the context. That is why order.total is checked without an annotation, and why the callback’s return value is checked against boolean.

The same thing in TypeScript

The TypeScript equivalent tab declares type OrderTest = (order: Order, index: number) => boolean; and the inline (order: Order) => void as a parameter annotation. A @callback block and a function type alias are interchangeable; tsc treats them the same.

What goes wrong

Because the callback’s parameter is typed from the context, a misspelled property inside it is caught where you write it (TS2551):

/** @typedef {{ id: string, total: number }} Order */

/**
 * @callback OrderTest
 * @param {Order} order
 * @returns {boolean}
 */

/**
 * @param {Order[]} orders
 * @param {OrderTest} keep
 */
export function pickOrders(orders, keep) {
  return orders.filter(keep);
}

pickOrders([], (order) => order.totl > 25);error TS2551: Property 'totl' does not exist on type 'Order'. Did you mean 'total'?

And the return type is part of the contract. A callback that returns the order’s id where a boolean is expected fails with TS2322:

/** @typedef {{ id: string, total: number }} Order */

/**
 * @callback OrderTest
 * @param {Order} order
 * @returns {boolean}
 */

/**
 * @param {Order[]} orders
 * @param {OrderTest} keep
 */
export function pickOrders(orders, keep) {
  return orders.filter(keep);
}

pickOrders([], (order) => order.id);error TS2322: Type 'string' is not assignable to type 'boolean'.

Gotchas

• A @callback without @returns returns any. The type stays open, so nothing checks what the callback gives back. Add @returns {void} when the result is ignored.
• Fewer parameters are fine. A callback that ignores index can leave it out, as (order) => … does above; JavaScript passes it anyway, and TypeScript allows it.
• @callback names are types, not values. Use them inside braces in JSDoc. In a .js file a @callback written at the top level of a module can be imported into another file with @import, like a @typedef.