JS with Types Start

Type expression

ReturnType<T>

  • Utility types
  • Since TypeScript 2.8

ReturnType<typeof createCart> is the type createCart() returns. When a factory function defines an object's shape, this names that shape for other functions' @param tags without repeating it, as Cart in the first example.

ReturnType takes a function type, so the usual spelling puts typeof in front of the function's name. TypeScript added it in version 2.8.

At a glance

JSDoc in a .js file TypeScript in a .ts file
/** @type {ReturnType<typeof createCart>} */ : ReturnType<typeof createCart>

Examples

cart.js cart.ts TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
export function createCart() {
  return {
    /** @type {{ sku: string, quantity: number }[]} */
    lines: [],
    coupon: /** @type {string | null} */ (null),
  };
}

/** @typedef {ReturnType<typeof createCart>} Cart */

/** @param {Cart} cart */
export function itemCount(cart) {
  return cart.lines.reduce((n, line) => n + line.quantity, 0);
}

itemCount(createCart());
export function createCart() {
  return {
    lines: [] as { sku: string; quantity: number }[],
    coupon: null as string | null,
  };
}

type Cart = ReturnType<typeof createCart>;

export function itemCount(cart: Cart) {
  return cart.lines.reduce((n, line) => n + line.quantity, 0);
}

itemCount(createCart());
ReturnType of a function, through typeof.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
cart.js cart.ts TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: cart.ts(6,24): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'? 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. cart.ts(6,24): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'? 7.0.2 : differs, see why TypeScript 7.0.2, run 21 October 2026: differs from 5.9.3. cart.js(6,23): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'? cart.ts(6,24): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'? checked 21 October 2026 
export function createCart() {
  return { lines: /** @type {string[]} */ ([]) };
}

// TypeScript resolves a value name in JSDoc to the value's type, so this passes in a .js file.
/** @type {ReturnType<createCart>} */
const cart = createCart();

export { cart };
export function createCart() {
  return { lines: [] as string[] };
}

const cart: ReturnType<createCart> = createCart();error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'?

export { cart };
In a .js file a function name also works as a type; in .ts it needs typeof.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

Without typeof in a .js file

In a .js file TypeScript resolves a value's name in a JSDoc type to the value's type, so ReturnType<createCart> works there too. The same line in a .ts file is TS2749 ("'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'?"); the second example shows both tabs. Write typeof so the type means the same in both kinds of file.

Async functions

For an async function, ReturnType is the Promise. Wrap it in Awaited for the resolved value: Awaited<ReturnType<typeof loadAccount>>.

Under TypeScript 6.0 and 7.0

Every example on this page also runs under TypeScript 6.0.3 and 7.0.2 when this site is built. One of them reports something different from 5.9.3, the version the page describes; the ✗ on its badge links to its entry below.

A value's name is not a type

TypeScript 7.0 · JSDoc and JavaScript patterns 7.0 no longer reads

The pattern: {ReturnType<createCart>} or {Status}, where createCart or Status is a value, not a type.

Why: 5.9 read a value's name in a JSDoc type as typeof that value, in .js files only. The port's list of changes says values are no longer resolved as types in JSDoc, so the .js file now reports TS2749, as its .ts twin always did. Source: CHANGES.md: Values are no longer resolved as types in JSDoc type positions.

In a .js file a function name also works as a type; in .ts it needs typeof cart.js

TypeScript 5.9.3
cart.ts(6,24): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'?
TypeScript 6.0.3same as 5.9.3

The same errors as 5.9.3.

TypeScript 7.0.2differs from 5.9.3
cart.js(6,23): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'?
cart.ts(6,24): error TS2749: 'createCart' refers to a value, but is being used as a type here. Did you mean 'typeof createCart'?

What works in every version: Write typeof: {ReturnType<typeof createCart>}.

The example ReturnType of a function, through typeof on this page shows it, with the same result under every version.

Gotchas

  • For an overloaded function, ReturnType uses the last overload.
  • The factory's return type must be clear to TypeScript; empty arrays and null initial values in the returned object need a @type comment or a cast, as in the first example, or TypeScript types them as never[] and null, and nothing else can be stored in them.
  • TypeScript 7.0 no longer accepts a value's name as a type: ReturnType<createCart> is TS2749 there (the section Under TypeScript 6.0 and 7.0), so write ReturnType<typeof createCart>.

Questions

How do I get a function's return type in JSDoc?

{ReturnType<typeof yourFunction>}. For an async function, {Awaited<ReturnType<typeof yourFunction>>}.

  • Type expression

    Awaited<T>

    Awaited<T> is the value a promise resolves to, unwrapped as await does. In JSDoc, Awaited<ReturnType<typeof fn>> names an async function's result.

  • Type expression

    Parameters<T>

    Parameters<typeof fn> is a tuple of a function's parameter types. Use it in JSDoc for wrappers that pass arguments through, or to name one parameter type.

  • Type expression

    typeof in types

    typeof in a JSDoc type gives you the type of a value, such as a config object or a function, without writing it twice. How it differs from JavaScript's typeof.

  • JSDoc tag

    @returns

    The JSDoc @returns tag declares a function's return type, and TypeScript checks every return against it. Async functions, void, and when to leave it out.

  • TypeScript release

    TypeScript 7.0 for JavaScript users

    TypeScript 7.0, the native port, for JavaScript: builds 8 to 12 times faster, and JSDoc is read like TypeScript, without @enum, @class or Closure types.

Sources

Last reviewed 21 October 2026.