TypeScript ReturnType, Parameters and Awaited Utility Types

ReturnType<T> gives the return type of a function type, and Parameters<T> gives its parameter types as a tuple. Apply them to a function value with typeof, so the types follow the function whenever it changes:

function createUser(name: string, age: number) {
    return { id: Math.floor(age * 1000), name, age, createdAt: "2024-03-15" };
}

type User = ReturnType<typeof createUser>;
// { id: number; name: string; age: number; createdAt: string }

type CreateUserArgs = Parameters<typeof createUser>;
// [name: string, age: number]

const args: CreateUserArgs = ["Ada", 36];
const user: User = createUser(...args);
console.log(user); // { id: 36000, name: 'Ada', age: 36, createdAt: '2024-03-15' }

User is never written out. Add a field to the object createUser returns and User has it too. This is the main use of these types: naming a type that already exists implicitly, often in code you do not own.

ReturnType Needs typeof

ReturnType takes a type, and a function name is a value. Passing the name directly is a compile error:

// This does not compile: createUser is a value, not a type.
function createUser(name: string) {
    return { name, active: true };
}

type User = ReturnType<createUser>;

const u: User = createUser("Ada");
console.log(u);

index.ts(6,24): error TS2749: 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'?

The fix is the one the message suggests: ReturnType<typeof createUser>. typeof in a type position asks for the type of a variable or function; see typeof for both meanings of that keyword.

ReturnType also works on a function type directly, without typeof: ReturnType<() => string> is string, and ReturnType<Handler> works when Handler is a function type alias.

Awaited and Async Functions

An async function returns a promise, so ReturnType gives Promise<...>. Awaited<T> unwraps it, the same way await does at runtime:

async function fetchSettings() {
    return { theme: "dark" as const, fontSize: 14 };
}

type SettingsPromise = ReturnType<typeof fetchSettings>;
// Promise<{ theme: "dark"; fontSize: number }>

type Settings = Awaited<ReturnType<typeof fetchSettings>>;
// { theme: "dark"; fontSize: number }

type Deep = Awaited<Promise<Promise<number>>>; // number: unwraps recursively

function applySettings(s: Settings): string {
    return `${s.theme} theme, ${s.fontSize}px`;
}

async function main() {
    const s = await fetchSettings();
    console.log(applySettings(s)); // dark theme, 14px
    const n: Deep = 5;
    console.log(n);
}
main();

Awaited<T> leaves a non-promise type unchanged (Awaited<string> is string), so it is safe to apply when you are not sure whether a function is async. The standard library's type for Promise.all uses it for the same reason.

Parameters

Parameters<T> returns the parameter list as a labeled tuple, including optional and rest parameters. Index into it for a single parameter's type. It is useful for wrapping a function without repeating its signature:

function sendEmail(to: string, subject: string, options?: { cc?: string[]; urgent?: boolean }) {
    return `to=${to} subject="${subject}" urgent=${options?.urgent ?? false}`;
}

type EmailArgs = Parameters<typeof sendEmail>;
// [to: string, subject: string, options?: { cc?: string[]; urgent?: boolean }]

type EmailOptions = Parameters<typeof sendEmail>[2];
// { cc?: string[]; urgent?: boolean } | undefined

// A wrapper that accepts exactly what sendEmail accepts.
function sendLogged(...args: EmailArgs): ReturnType<typeof sendEmail> {
    console.log("sending", args.length, "args");
    return sendEmail(...args);
}

const opts: EmailOptions = { urgent: true };
console.log(sendLogged("ada@example.com", "Hi", opts));
// sending 3 args
// to=ada@example.com subject="Hi" urgent=true

Parameters<typeof fn>[2] includes undefined because the parameter is optional. Wrap it in NonNullable to get the object type alone.

ConstructorParameters and InstanceType

The class counterparts: ConstructorParameters<typeof C> is the constructor's parameter tuple, and InstanceType<typeof C> is the type of the object new C(...) returns. For a class you can name directly, the instance type is just C; InstanceType is for generic code that receives a class as a value:

class Point {
    constructor(public x: number, public y: number) {}
}

type PointArgs = ConstructorParameters<typeof Point>; // [x: number, y: number]
type P = InstanceType<typeof Point>;                  // Point

// Build any class from its constructor arguments.
function build<C extends new (...args: any[]) => object>(
    ctor: C,
    ...args: ConstructorParameters<C>
): InstanceType<C> {
    return new ctor(...args) as InstanceType<C>;
}

const p: P = build(Point, 3, 4);
console.log(p, p instanceof Point); // Point { x: 3, y: 4 } true

const date = build(Date, "2024-03-15T10:30:00Z");
console.log(date.toISOString()); // 2024-03-15T10:30:00.000Z

const args: PointArgs = [1, 2];
console.log(new Point(...args)); // Point { x: 1, y: 2 }

build(Point, 3, "4") would be a compile error, because the rest parameter is typed from Point's own constructor. The as InstanceType<C> cast is needed because TypeScript cannot prove that new ctor(...) produces exactly InstanceType<C> for a generic C.

Overloads and Generic Functions

Two cases where the result may not be what you expect:

function parse(input: string): string[];
function parse(input: number): number[];
function parse(input: string | number): string[] | number[] {
    return typeof input === "string" ? input.split(",") : [input];
}

type Parsed = ReturnType<typeof parse>; // number[]: only the last overload counts
const nums: Parsed = [1, 2];

function identity<T>(value: T): T {
    return value;
}

type Id = ReturnType<typeof identity>; // unknown: T has no argument to infer from
const x: Id = "anything";

// For a specific instantiation, use an instantiation expression:
type IdOfNumber = ReturnType<typeof identity<number>>; // number

const y: IdOfNumber = 42;
console.log(nums, x, y); // [ 1, 2 ] anything 42

For overloads, ReturnType and Parameters look only at the last signature, so put the most general overload last or name the types explicitly. For generic functions, a type parameter with no argument becomes its constraint (unknown here); typeof identity<number> fixes it to one instantiation.

How ReturnType Is Built

All of these are conditional types with infer, defined in the standard library. Simplified:

type ReturnType<T extends (...args: any) => any> =
    T extends (...args: any) => infer R ? R : any;

type Parameters<T extends (...args: any) => any> =
    T extends (...args: infer P) => any ? P : never;

type InstanceType<T extends abstract new (...args: any) => any> =
    T extends abstract new (...args: any) => infer R ? R : any;

infer R declares a type variable that TypeScript fills in by matching T against the pattern. The constraint on T is why ReturnType<string> is an error: string is not a function type. You can write your own extractors the same way, for example the element type of an array or the type a promise resolves to; the conditional types page shows how.