TypeScript 36 🔷 Utility Types — ReturnType, Parameters, Awaited, InstanceType - KandZ

The previous two chapters covered utilities for objects (Partial, Pick, Omit, Record) and unions (Exclude, Extract, NonNullable). This chapter covers the utilities that work with functions and constructors: ReturnType<T> extracts a function’s return type, Parameters<T> extracts its parameter tuple, Awaited<T> unwraps a promise (recursively), and InstanceType<T> extracts the instance type from a constructor. All four are built on infer — the keyword from Chapter 32 that captures a type inside a conditional pattern. Learn these, and you can type the pieces of any function or class without duplicating them.

Key point: Each of these utilities answers a specific question about a function or constructor. ReturnType — “what does it return?” Parameters — “what does it take?” Awaited — “what’s the resolved value?” InstanceType — “what does new produce?” They’re all infer in a pattern: a function pattern for ReturnType and Parameters, a promise pattern for Awaited, a constructor pattern for InstanceType. Once you can read them, you can write your own — every “extract X from a function” utility is the same shape.

`ReturnType<T>` — the function’s return type

ReturnType<T> gives the type a function returns.

function greet(name: string): string {
  return `Hello, ${name}`;
}

type GreetReturn = ReturnType<typeof greet>;
// string

typeof greet is the function’s type; ReturnType extracts what it returns.

Implementation:

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

The conditional matches a function pattern and captures the return type as R.

On arrow functions and methods:

const add = (a: number, b: number) => a + b;
type AddReturn = ReturnType<typeof add>;
// number

class Calculator {
  multiply(a: number, b: number): number { return a * b; }
}

type MultiplyReturn = ReturnType<Calculator['multiply']>;
// number

Calculator['multiply'] is the method type — indexed access on the class instance type.

On async functions: An async function returns a Promise<T>. ReturnType gives the promise, not the resolved value.

async function fetchUser(id: number): Promise<User> {
  const res = await fetch(`/users/${id}`);
  return res.json();
}

type FetchReturn = ReturnType<typeof fetchUser>;
// Promise<User>

type FetchValue = Awaited<ReturnType<typeof fetchUser>>;
// User

Combine ReturnType with Awaited to get the resolved value.

On generic functions:

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

type IdentityReturn = ReturnType<typeof identity>;
// unknown — T is unresolved

Without a concrete type argument, the return is unknown. Use an instantiated version:

type StringIdentity = ReturnType<typeof identity<string>>;
// string

Why ReturnType matters: You often need to type a variable or parameter as “whatever this function returns” without repeating the type. ReturnType derives it. If the function’s return type changes, every consumer updates automatically.

The constraint T extends (...args: any) => any: The type argument must be a function. This prevents misuse and lets the conditional pattern match.

When ReturnType doesn’t work: When T is any, or when T isn’t a function. The result is any or a compile error.

Why “ReturnType” and not “Output”: TypeScript uses the term from the function signature — the return. “Return type” is the standard term in languages with typed functions. Keeping it familiar means less to learn.

`Parameters<T>` — the function’s parameter tuple

Parameters<T> gives a function’s parameter types as a tuple.

function createUser(name: string, age: number): User {
  return { name, age };
}

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

The result is a labeled tuple — position and name preserved.

Implementation:

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

The conditional captures the parameter list as P.

Accessing individual parameters:

type FirstName = Parameters<typeof createUser>[0];
// string

type Age = Parameters<typeof createUser>[1];
// number

Index into the tuple to get one parameter.

Spread and rest:

function log(level: string, ...messages: string[]): void { }

type LogParams = Parameters<typeof log>;
// [level: string, ...messages: string[]]

The tuple includes the rest parameter.

On methods:

class Api {
  request(url: string, method: 'GET' | 'POST'): Promise<Response> {
    // ...
  }
}

type RequestParams = Parameters<Api['request']>;
// [url: string, method: 'GET' | 'POST']

On constructors: Parameters doesn’t work directly on class constructors — use ConstructorParameters<T> for that.

class User {
  constructor(public name: string, public age: number) {}
}

type UserCtorParams = ConstructorParameters<typeof User>;
// [name: string, age: number]

ConstructorParameters<T> is the constructor equivalent of Parameters.

Why Parameters matters: Wrapping or forwarding functions requires knowing their parameter types. Parameters extracts them so wrappers can be typed precisely.

function withLogging<T extends (...args: any[]) => any>(fn: T): T {
  return ((...args: Parameters<T>) => {
    console.log('called with', args);
    return fn(...args);
  }) as T;
}

withLogging forwards arguments to fn — Parameters<T> types them.

On functions with no parameters:

function now(): number { return Date.now(); }

type NowParams = Parameters<typeof now>;
// []

The tuple is empty.

Why the tuple and not an array: Positional parameters are a tuple — each slot has a specific type. Typing them as an array would lose that.

Why “Parameters” is the right name: It’s plural because functions have many parameters. The tuple captures them in order. The name matches the mental model of “what does this function take?”

Why labeled tuples: The parameter names are preserved in the tuple — [name: string, age: number]. That’s for editors and tooling; the types are what matter. Labels make hover tooltips readable.

`Awaited<T>` — unwrap a promise, recursively

Awaited<T> gives the resolved value of a promise, unwrapping nested promises.

type A = Awaited<Promise<string>>;
// string

type B = Awaited<Promise<Promise<number>>>;
// number

type C = Awaited<string>;
// string (not a promise)

Awaited recurses through nested promises until it reaches a non-promise.

Implementation:

type Awaited<T> =
  T extends null | undefined ? T :
  T extends object & { then(onfulfilled: infer F, ...args: any[]): any }
    ? F extends (value: infer V, ...args: any[]) => any
      ? Awaited<V>
      : never
    : T;

The definition is complex because it matches anything with a then method — not just Promise. TypeScript’s actual implementation handles thenables too.

On async function returns:

async function fetchUser(): Promise<User> {
  return { id: 1, name: 'Alice' };
}

type UserPromise = ReturnType<typeof fetchUser>;
// Promise<User>

type User = Awaited<UserPromise>;
// User

The common pattern: Awaited<ReturnType<T>> gives the resolved value of an async function.

On non-promise values:

type A = Awaited<string>;
// string

If T isn’t a promise, Awaited<T> returns T unchanged. That makes it safe to apply to any type.

On PromiseLike:

interface MyPromise<T> {
  then<R>(onfulfilled: (value: T) => R): MyPromise<R>;
}

type A = Awaited<MyPromise<string>>;
// string

Anything with a then method is treated as thenable.

Why Awaited matters: async functions hide the resolved type behind Promise. Awaited recovers it. It’s how you write “the value this async function returns” without duplicating the type.

In Promise.all and similar:

const promises = [Promise.resolve(1), Promise.resolve('a')] as const;
type Values = Awaited<(typeof promises)[number]>;
// 1 | 'a'

Awaited distributed over the union of promise types gives the union of resolved values.

Why recursion: A promise can resolve to another promise. Promise<Promise<T>> resolves to T after two awaits. Awaited handles arbitrary depth.

Why Awaited was added: Before TypeScript 4.5, unwrapping promises required a custom conditional. Awaited made it standard — and handled thenables, recursion, and edge cases correctly.

Why “Awaited” and not “Unwrap”: It’s the past-tense of “await” — the type you get after awaiting the promise. The name matches the operation: await promise gives the awaited value. The utility gives the awaited type.

`InstanceType<T>` — the constructor’s instance

InstanceType<T> gives the instance type a constructor produces.

class User {
  name = '';
  greet(): string { return `Hi, ${this.name}`; }
}

type UserInstance = InstanceType<typeof User>;
// User

typeof User is the constructor type; InstanceType extracts what new User() produces.

Implementation:

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

The conditional matches a constructor pattern and captures the instance type.

On abstract classes:

abstract class Animal {
  abstract speak(): string;
}

class Dog extends Animal {
  speak(): string { return 'woof'; }
}

type AnimalInstance = InstanceType<typeof Animal>;
// Animal

InstanceType works on abstract constructors too — the constraint is abstract new.

In factory functions:

function create<T extends new () => object>(Ctor: T): InstanceType<T> {
  return new Ctor();
}

const user = create(User);
// User

InstanceType<T> gives the correct type for the factory’s return.

On built-in constructors:

type DateInstance = InstanceType<typeof Date>;
// Date

type MapInstance = InstanceType<typeof Map>;
// Map<any, any>

For generics, the instance type uses its default type arguments.

Why InstanceType matters: Given a class reference, you often need the instance type — for a factory, a registry, or a decorator. InstanceType derives it from the constructor type.

The distinction from typeof:

type A = typeof User;         // constructor type
type B = InstanceType<typeof User>;  // instance type
type C = User;                // instance type

typeof User and User are different — one is the constructor, the other is what it produces. InstanceType bridges them.

Why “Instance”: The result of new is an instance. The utility gives the instance type — what you get when you call new. The name matches the outcome.

Why not just use User directly: When you have the class as a value (like typeof User), you can’t always name the instance type directly. InstanceType derives it. That’s essential in generics and factories, where the class is a type parameter.

Combining the four

These utilities combine in real patterns.

Wrap a function preserving its signature:

function memoize<T extends (...args: any[]) => any>(fn: T): T {
  const cache = new Map<string, ReturnType<T>>();
  return ((...args: Parameters<T>) => {
    const key = JSON.stringify(args);
    if (!cache.has(key)) {
      cache.set(key, fn(...args));
    }
    return cache.get(key);
  }) as T;
}

Parameters<T> types the wrapper’s parameters; ReturnType<T> types the cached value.

Async wrapper:

type AsyncFn<T> = (...args: Parameters<T>) => Promise<ReturnType<T>>;

function promisify<T extends (...args: any[]) => any>(
  fn: T
): AsyncFn<T> {
  return (...args) => Promise.resolve(fn(...args));
}

Takes a sync function, returns an async version with the same parameters.

Class factory:

function makeFactory<T extends new (...args: any[]) => any>(
  Ctor: T
): (...args: ConstructorParameters<T>) => InstanceType<T> {
  return (...args) => new Ctor(...args);
}

const createUser = makeFactory(User);
const user = createUser('Alice', 30);  // User

Constructor parameters go in, an instance comes out.

Async wrapper with resolved type:

async function fetchData<T>(url: string): Promise<T> {
  const res = await fetch(url);
  return res.json();
}

type FetchedUser = Awaited<ReturnType<typeof fetchData<User>>>;
// User

Chain Awaited and ReturnType to get the resolved value of an async function.

Extracting service method signatures:

class UserService {
  getUser(id: number, includeDeleted: boolean): Promise<User> {
    // ...
  }
}

type GetUserParams = Parameters<UserService['getUser']>;
// [id: number, includeDeleted: boolean]

type GetUserResult = Awaited<ReturnType<UserService['getUser']>>;
// User

The parameters and the resolved result are both derived from the method.

Why these combinations matter: Real code wraps, forwards, and delegates. The utilities extract the pieces so wrappers can be typed without duplicating signatures. Every decorator, middleware, and higher-order function uses them.

Why Parameters and ReturnType pair naturally: They’re complements. Together they describe the full signature — inputs and outputs. Wrappers need both to preserve the shape.

A full example

A typed middleware system using the four utilities.

// ============================================
// BASIC FUNCTION
// ============================================

interface User {
  id: number;
  name: string;
  email: string;
}

class UserRepository {
  async getUser(id: number, includeDeleted: boolean = false): Promise<User> {
    const res = await fetch(`/users/${id}?deleted=${includeDeleted}`);
    return res.json();
  }

  async saveUser(user: User): Promise<void> {
    await fetch('/users', {
      method: 'POST',
      body: JSON.stringify(user)
    });
  }
}

// ============================================
// EXTRACTING SIGNATURES
// ============================================

type GetUserMethod = UserRepository['getUser'];
type GetUserParams = Parameters<GetUserMethod>;
// [id: number, includeDeleted?: boolean]

type GetUserPromise = ReturnType<GetUserMethod>;
// Promise<User>

type GetUserResult = Awaited<GetUserPromise>;
// User

type SaveUserParams = Parameters<UserRepository['saveUser']>;
// [user: User]

// ============================================
// WRAPPING WITH LOGGING
// ============================================

function withLogging<T extends (...args: any[]) => any>(fn: T): T {
  return ((...args: Parameters<T>): ReturnType<T> => {
    console.log(`Calling with ${args.length} args`);
    const result = fn(...args);
    console.log('Call returned');
    return result;
  }) as T;
}

// ============================================
// WRAPPING WITH RETRY
// ============================================

function withRetry<T extends (...args: any[]) => Promise<any>>(
  fn: T,
  attempts = 3
): (...args: Parameters<T>) => ReturnType<T> {
  return async (...args) => {
    let lastError: unknown;
    for (let i = 0; i < attempts; i++) {
      try {
        return await fn(...args);
      } catch (err) {
        lastError = err;
      }
    }
    throw lastError;
  };
}

// ============================================
// CLASS FACTORY
// ============================================

function createRepository<T extends new (...args: any[]) => any>(
  Ctor: T
): (...args: ConstructorParameters<T>) => InstanceType<T> {
  return (...args) => new Ctor(...args);
}

// ============================================
// USAGE
// ============================================

const repo = createRepository(UserRepository);
// repo: () => UserRepository

const loggedRepo = withLogging(repo);
const appRepo = loggedRepo();

// Wrap the method with retry
const retryGetUser = withRetry(appRepo.getUser.bind(appRepo));

async function main(): Promise<void> {
  const user = await retryGetUser(42, false);
  // user: User

  console.log(user.name);
}

// ============================================
// TYPE-LEVEL VERIFICATION
// ============================================

// These would be compile errors if the types were wrong:
type _Check1 = GetUserResult extends User ? true : false;   // true
type _Check2 = GetUserParams extends [number, boolean?] ? true : false;  // true
type _Check3 = InstanceType<typeof UserRepository> extends UserRepository ? true : false;  // true

console.log('Types verified');

What this shows:

Parameters<UserRepository['getUser']> — the parameter tuple
ReturnType<UserRepository['getUser']> — the promise
Awaited<...> — the resolved value
InstanceType<typeof UserRepository> — the class instance
ConstructorParameters<typeof UserRepository> — the constructor arguments
withLogging — wraps any function, preserving its signature via Parameters<T> and ReturnType<T>
withRetry — wraps an async function, preserving parameters and return type
createRepository — factory with constructor parameters in, instance out

Every wrapper keeps the exact signature. No duplication, no any.

Why this shape: It’s how real middleware works. Wrappers preserve the function they wrap — the same parameters, the same return type. The utilities make that possible at the type level. The compiler checks that a wrapper matches its target.

Complete Example Session

# ============================================
# PART 1: RETURN TYPE
# ============================================

cat > return.ts << 'EOF'
function add(a: number, b: number): number {
  return a + b;
}

type AddReturn = ReturnType<typeof add>;
// number

const result: AddReturn = 42;

// Async function
async function fetchUser(): Promise<{ id: number }> {
  return { id: 1 };
}

type FetchReturn = ReturnType<typeof fetchUser>;
// Promise<{ id: number }>

const p: FetchReturn = Promise.resolve({ id: 1 });

console.log(result, p);
EOF

npx tsc --noEmit return.ts
# (no errors)

# ============================================
# PART 2: PARAMETERS
# ============================================

cat > params.ts << 'EOF'
function createUser(name: string, age: number): void {}

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

const args: Params = ['Alice', 30];

function log(level: string, ...messages: string[]): void {}

type LogParams = Parameters<typeof log>;
// [level: string, ...messages: string[]]

const logArgs: LogParams = ['INFO', 'a', 'b', 'c'];

console.log(args, logArgs);
EOF

npx tsc --noEmit params.ts
# (no errors)

# ============================================
# PART 3: AWAITED
# ============================================

cat > awaited.ts << 'EOF'
type A = Awaited<Promise<string>>;
type B = Awaited<Promise<Promise<number>>>;
type C = Awaited<string>;

const a: A = 'hello';
const b: B = 42;
const c: C = 'not a promise';

// Async function resolved type
async function getData(): Promise<{ data: string }> {
  return { data: 'x' };
}

type Result = Awaited<ReturnType<typeof getData>>;
// { data: string }

const r: Result = { data: 'x' };

console.log(a, b, c, r);
EOF

npx tsc --noEmit awaited.ts
# (no errors)

# ============================================
# PART 4: INSTANCE TYPE
# ============================================

cat > instance.ts << 'EOF'
class User {
  constructor(public name: string) {}

  greet(): string {
    return `Hi, ${this.name}`;
  }
}

type Instance = InstanceType<typeof User>;
// User

type CtorParams = ConstructorParameters<typeof User>;
// [name: string]

const user: Instance = new User('Alice');
const args: CtorParams = ['Bob'];

console.log(user.greet(), args);
EOF

npx tsc --noEmit instance.ts
# (no errors)

# ============================================
# PART 5: WRAPPERS
# ============================================

cat > wrappers.ts << 'EOF'
function memoize<T extends (...args: any[]) => any>(fn: T): T {
  const cache = new Map<string, ReturnType<T>>();
  return ((...args: Parameters<T>): ReturnType<T> => {
    const key = JSON.stringify(args);
    if (!cache.has(key)) {
      cache.set(key, fn(...args));
    }
    return cache.get(key);
  }) as T;
}

function slowAdd(a: number, b: number): number {
  console.log('computing');
  return a + b;
}

const cachedAdd = memoize(slowAdd);

console.log(cachedAdd(1, 2));
console.log(cachedAdd(1, 2));  // cached, no log

function withLogging<T extends (...args: any[]) => any>(fn: T): T {
  return ((...args: Parameters<T>): ReturnType<T> => {
    console.log('calling with', args);
    return fn(...args);
  }) as T;
}

const loggedAdd = withLogging(slowAdd);
loggedAdd(3, 4);
EOF

npx tsc --noEmit wrappers.ts
# (no errors)

# ============================================
# PART 6: ASYNC WRAPPERS
# ============================================

cat > async-wrapper.ts << 'EOF'
function withRetry<T extends (...args: any[]) => Promise<any>>(
  fn: T,
  attempts = 3
): (...args: Parameters<T>) => ReturnType<T> {
  return async (...args) => {
    let lastError: unknown;
    for (let i = 0; i < attempts; i++) {
      try {
        return await fn(...args);
      } catch (err) {
        lastError = err;
      }
    }
    throw lastError;
  };
}

async function fetchData(url: string): Promise<{ status: number }> {
  return { status: 200 };
}

const robustFetch = withRetry(fetchData);

async function main(): Promise<void> {
  const result = await robustFetch('/api');
  // result: { status: number }
  console.log(result.status);
}

main();
EOF

npx tsc --noEmit async-wrapper.ts
# (no errors)

# ============================================
# PART 7: FACTORY
# ============================================

cat > factory.ts << 'EOF'
class Service {
  constructor(private apiUrl: string, private timeout: number) {}

  fetch(): string {
    return `fetching from ${this.apiUrl} with timeout ${this.timeout}`;
  }
}

function createService<T extends new (...args: any[]) => any>(
  Ctor: T
): (...args: ConstructorParameters<T>) => InstanceType<T> {
  return (...args) => new Ctor(...args);
}

const makeService = createService(Service);
const s = makeService('/api', 5000);

console.log(s.fetch());
EOF

npx tsc --noEmit factory.ts
# (no errors)

# ============================================
# PART 8: COMPILE AND RUN
# ============================================

npx tsc return.ts params.ts awaited.ts instance.ts wrappers.ts async-wrapper.ts factory.ts
node return.js
# [ 42 Promise { { id: 1 } } ]

node params.js
# [ [ 'Alice', 30 ] [ 'INFO', 'a', 'b', 'c' ] ]

node awaited.js
# [ hello 42 not a promise { data: 'x' } ]

node instance.js
# [ Hi, Alice [ 'Bob' ] ]

node wrappers.js
# [ computing ]
# [ 3 ]
# [ 3 ]
# [ calling with [ 3, 4 ] ]
# [ computing ]
# [ 7 ]

node async-wrapper.js
# [ 200 ]

node factory.js
# [ fetching from /api with timeout 5000 ]

Quick Reference

The Four Utilities

Utility	Extracts
`ReturnType<T>`	Function return type
`Parameters<T>`	Function parameter tuple
`Awaited<T>`	Resolved value of a promise
`InstanceType<T>`	Instance from a constructor

Implementations

Utility	Definition
`ReturnType<T>`	`T extends (...a: any) => infer R ? R : any`
`Parameters<T>`	`T extends (...a: infer P) => any ? P : never`
`Awaited<T>`	Recursive thenable unwrap
`InstanceType<T>`	`T extends abstract new (...a) => infer R ? R : any`

Constraints

Utility	Constraint
`ReturnType<T>`	`T extends (...args: any) => any`
`Parameters<T>`	`T extends (...args: any) => any`
`Awaited<T>`	None
`InstanceType<T>`	`T extends abstract new (...args: any) => any`

Related Utilities

Utility	Extracts
`ConstructorParameters<T>`	Constructor parameter tuple
`ThisParameterType<T>`	`this` parameter type
`OmitThisParameter<T>`	Function without `this`

Common Patterns

Pattern	Code
Function return	`ReturnType<typeof fn>`
Method return	`ReturnType<Class['method']>`
Async resolved	`Awaited<ReturnType<typeof fn>>`
Function params	`Parameters<typeof fn>`
Method params	`Parameters<Class['method']>`
Class instance	`InstanceType<typeof Class>`
Constructor params	`ConstructorParameters<typeof Class>`
Wrapper	`<T extends Fn>(fn: T): T`

Practical Examples

Need	Code
Type a variable from fn result	`type R = ReturnType<typeof fn>`
Type wrapper args	`...args: Parameters<T>`
Type cache value	`Map<string, ReturnType<T>>`
Type factory return	`InstanceType<T>`
Type factory args	`ConstructorParameters<T>`
Get async value	`Awaited<ReturnType<typeof asyncFn>>`
Get single param	`Parameters<typeof fn>[0]`
Get last param	`Parameters<typeof fn>[N]`

Function Type Constraints

Constraint	Meaning
`(...args: any) => any`	Any function
`(...args: any[]) => Promise<any>`	Any async function
`new (...args: any) => any`	Any constructor
`abstract new (...args: any) => any`	Any constructor (incl. abstract)

On Methods vs Functions

Source	Type extraction
Function	`typeof fn`
Method	`Class['method']`
Instance method	`InstanceType<typeof C>['method']`

Generic Functions

Issue	Solution
`ReturnType<typeof genericFn>` → unknown	Use `typeof genericFn<T>`
Unresolved type param	Instantiate with a concrete type

Error Cases

Error	Cause
`does not satisfy the constraint`	Non-function to `ReturnType`
`Expected function, got X`	Non-constructor to `InstanceType`
`unknown` result	Unresolved generic
`any` result	`T` is `any`

Wrapper Pattern

function wrap<T extends (...args: any[]) => any>(fn: T): T {
  return ((...args: Parameters<T>): ReturnType<T> => {
    // pre
    const result = fn(...args);
    // post
    return result;
  }) as T;
}

Async Wrapper Pattern

function asyncWrap<T extends (...args: any[]) => Promise<any>>(
  fn: T
): (...args: Parameters<T>) => ReturnType<T> {
  return async (...args) => {
    return fn(...args);
  };
}

Factory Pattern

function factory<T extends new (...args: any[]) => any>(
  Ctor: T
): (...args: ConstructorParameters<T>) => InstanceType<T> {
  return (...args) => new Ctor(...args);
}

When to Use Each

Need	Utility
Function’s return	`ReturnType`
Function’s args	`Parameters`
Async resolved value	`Awaited`
Class instance type	`InstanceType`
Constructor args	`ConstructorParameters`

Best Practices

✅ Do This:

// Use ReturnType to avoid duplicating
type User = ReturnType<typeof fetchUser>;                    // ✅

// Use Parameters for wrappers
function wrap<T extends Fn>(fn: T): T {
  return ((...args: Parameters<T>) => fn(...args)) as T;
}                                                            // ✅

// Use Awaited for async resolved types
type User = Awaited<ReturnType<typeof fetchUser>>;           // ✅

// Use InstanceType in factories
function create<T extends new () => object>(C: T): InstanceType<T> {
  return new C();
}                                                            // ✅

// Use ConstructorParameters for factory args
type Args = ConstructorParameters<typeof User>;              // ✅

// Combine Awaited and ReturnType for async functions
type Value = Awaited<ReturnType<typeof asyncFn>>;            // ✅

// Type wrappers preserving signatures
function memoize<T extends Fn>(fn: T): T {
  const cache = new Map<string, ReturnType<T>>();
  return ((...args: Parameters<T>) => {
    // ...
  }) as T;
}                                                            // ✅

// Use typeof for function values
type R = ReturnType<typeof fn>;                              // ✅

// Use indexed access for methods
type R = ReturnType<Service['method']>;                      // ✅

// Verify with type checks
type _ = ReturnType<typeof fn> extends string ? true : false; // ✅

❌ Don’t Do This:

// Don't use ReturnType on non-functions
type Bad = ReturnType<string>;  // ❌                            // ❌

// Don't expect ReturnType to unwrap promises
type R = ReturnType<typeof asyncFn>;
// Promise<T>, not T — use Awaited                              // ⚠️

// Don't forget InstanceType for constructors
type Bad = ReturnType<typeof User>;  // ❌ wrong                  // ❌

// Don't use Parameters on constructors
type Bad = Parameters<typeof User>;  // ⚠️  empty or error        // ⚠️

// Don't rely on generic ReturnType without instantiation
type R = ReturnType<typeof genericFn>;
// unknown — T unresolved                                       // ⚠️

// Don't duplicate what these utilities extract
type Params = [id: number, flag: boolean];  // ⚠️
// Use Parameters<typeof fn> instead                            // ✅

// Don't cast wrappers unsafely
function wrap(fn: any): any { }  // ⚠️  loses types             // ⚠️

// Don't over-nest utility calls
type Complex = Awaited<ReturnType<typeof fn<Awaited<...>>>>;    // ⚠️

Common Pitfalls

Pitfall	Problem	Solution
`ReturnType` on async	Gives `Promise<T>`	Use `Awaited`
`ReturnType` on non-function	Compile error	Check the input
`Parameters` on constructor	Wrong result	Use `ConstructorParameters`
`InstanceType` without `typeof`	Wrong	`InstanceType<typeof C>`
Unresolved generic	`unknown`	Instantiate with concrete type
Mixing `typeof` and `InstanceType`	Wrong type	Understand the difference
Casting wrappers	Loses type safety	Use `T` generics
Forgetting constraints	Compile error	Add `extends (...args: any) => any`
Deep nesting	Unreadable	Extract named types
Expecting `Awaited` to change sync types	No-op	It’s safe

Real-World Examples

1. Function return type

type R = ReturnType<typeof fetchUser>;

2. Method return type

type R = ReturnType<Service['method']>;

3. Async resolved

type Value = Awaited<ReturnType<typeof asyncFn>>;

4. Function parameters

type P = Parameters<typeof createUser>;

5. Method parameters

type P = Parameters<Service['method']>;

6. First parameter

type First = Parameters<typeof fn>[0];

7. Class instance

type I = InstanceType<typeof User>;

8. Constructor params

type P = ConstructorParameters<typeof User>;

9. Memoize wrapper

function memoize<T extends Fn>(fn: T): T {
  const cache = new Map<string, ReturnType<T>>();
  return ((...args: Parameters<T>) => {
    const k = JSON.stringify(args);
    if (!cache.has(k)) cache.set(k, fn(...args));
    return cache.get(k);
  }) as T;
}

10. Retry wrapper

function withRetry<T extends (...a: any[]) => Promise<any>>(fn: T): T {
  return (async (...args: Parameters<T>) => {
    for (let i = 0; i < 3; i++) {
      try { return await fn(...args); } catch { }
    }
  }) as T;
}

11. Timing wrapper

function timed<T extends Fn>(fn: T): T {
  return ((...args: Parameters<T>): ReturnType<T> => {
    const start = performance.now();
    const result = fn(...args);
    console.log(performance.now() - start);
    return result;
  }) as T;
}

12. Class factory

function factory<T extends new (...a: any[]) => any>(
  Ctor: T
): (...args: ConstructorParameters<T>) => InstanceType<T> {
  return (...args) => new Ctor(...args);
}

13. Typed event handler

class EventBus {
  on(event: string, handler: (...args: any[]) => void): void {}
}

type Handler = Parameters<EventBus['on']>[1];

14. Get async value type

async function fetchUser(): Promise<User> { /* ... */ }
type User = Awaited<ReturnType<typeof fetchUser>>;

15. Get promise type

type P = ReturnType<typeof fetchUser>;
// Promise<User>

16. Wrapper that preserves type

function debounce<T extends Fn>(fn: T, ms: number): T {
  let timer: number;
  return ((...args: Parameters<T>) => {
    clearTimeout(timer);
    timer = window.setTimeout(() => fn(...args), ms);
  }) as T;
}

17. Extract method parameters

type Params = Parameters<Map<string, number>['set']>;
// [key: string, value: number]

18. Method call signature

type Call = (...args: Parameters<Service['method']>) => ReturnType<Service['method']>;

19. Constructor type

type Ctor = new (...args: ConstructorParameters<typeof User>) => InstanceType<typeof User>;

20. Async wrapper with typed params

function promisify<T extends (...args: any[]) => any>(
  fn: T
): (...args: Parameters<T>) => Promise<ReturnType<T>> {
  return (...args) => Promise.resolve(fn(...args));
}

Visual: The Four Utilities

┌──────────────────────────────────────────────┐
│  function fn(a: string, b: number): boolean  │
│                                              │
└──────────────────────────────────────────────┘
       │
       ├─────────► ReturnType<typeof fn>
       │           → boolean
       │
       ├─────────► Parameters<typeof fn>
       │           → [a: string, b: number]
       │
       └─────────► fn itself

┌──────────────────────────────────────────────┐
│  Promise<Promise<string>>                    │
│                                              │
└──────────────────────────────────────────────┘
       │
       └─────────► Awaited<...>
                   → string

┌──────────────────────────────────────────────┐
│  class User { }                              │
│                                              │
└──────────────────────────────────────────────┘
       │
       └─────────► InstanceType<typeof User>
                   → User

Visual: ReturnType

┌──────────────────────────────────────────────┐
│  function greet(name: string): string {      │
│    return `Hello, ${name}`;                  │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘
       │
       │  typeof greet
       ▼
┌──────────────────────────────────────────────┐
│  (name: string) => string                    │
│                                              │
└──────────────────────────────────────────────┘
       │
       │  ReturnType<...>
       ▼
┌──────────────────────────────────────────────┐
│  string                                      │
│                                              │
└──────────────────────────────────────────────┘

Visual: Parameters

┌──────────────────────────────────────────────┐
│  function createUser(                        │
│    name: string,                             │
│    age: number                               │
│  ): User { }                                 │
│                                              │
└──────────────────────────────────────────────┘
       │
       │  Parameters<typeof createUser>
       ▼
┌──────────────────────────────────────────────┐
│  [name: string, age: number]                 │
│                                              │
│  Indexed access:                             │
│  [0] → string                                │
│  [1] → number                                │
│                                              │
└──────────────────────────────────────────────┘

Visual: Awaited

┌──────────────────────────────────────────────┐
│  Promise<string>                             │
│       │                                      │
│       │  Awaited                             │
│       ▼                                      │
│  string                                      │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Promise<Promise<number>>                    │
│       │                                      │
│       │  Awaited (recursive)                 │
│       ▼                                      │
│  Promise<number>                             │
│       │                                      │
│       ▼                                      │
│  number                                      │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  string (not a promise)                      │
│       │                                      │
│       │  Awaited                             │
│       ▼                                      │
│  string (unchanged)                          │
│                                              │
└──────────────────────────────────────────────┘

Visual: InstanceType

┌──────────────────────────────────────────────┐
│  class User {                                │
│    constructor(public name: string) {}       │
│    greet() { }                               │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  typeof User                                 │
│  → constructor type                          │
│    new (name: string) => User                │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  InstanceType<typeof User>                   │
│  → User (instance type)                      │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  User                                        │
│  → the same instance type                    │
│                                              │
│  InstanceType<typeof User> === User          │
│                                              │
└──────────────────────────────────────────────┘

Visual: Wrapper Pattern

┌──────────────────────────────────────────────┐
│  function memoize<T extends Fn>(fn: T): T {  │
│    const cache = new Map<string, ReturnType<T>>();│
│    return ((...args: Parameters<T>) => {     │
│      const key = JSON.stringify(args);       │
│      if (!cache.has(key)) {                  │
│        cache.set(key, fn(...args));          │
│      }                                       │
│      return cache.get(key);                  │
│    }) as T;                                  │
│  }                                           │
│                                              │
│  Parameters<T>   → wrapper's args            │
│  ReturnType<T>   → cache value type          │
│  T               → wrapper's type            │
│                                              │
└──────────────────────────────────────────────┘

Visual: Async Pipeline

┌──────────────────────────────────────────────┐
│  async function fetchUser(): Promise<User>   │
│                                              │
└──────────────────────────────────────────────┘
       │
       │  ReturnType
       ▼
┌──────────────────────────────────────────────┐
│  Promise<User>                               │
│                                              │
└──────────────────────────────────────────────┘
       │
       │  Awaited
       ▼
┌──────────────────────────────────────────────┐
│  User                                        │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Combined:                                   │
│                                              │
│  type User = Awaited<ReturnType<typeof fetchUser>>;│
│                                              │
└──────────────────────────────────────────────┘

Visual: Factory Pattern

┌──────────────────────────────────────────────┐
│  class Service {                             │
│    constructor(url: string, t: number) {}    │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  function factory<T extends new (...a: any[]) => any>(│
│    Ctor: T                                   │
│  ): (...args: ConstructorParameters<T>) => InstanceType<T> {│
│    return (...args) => new Ctor(...args);    │
│  }                                           │
│                                              │
│  ConstructorParameters<T> → factory's args   │
│  InstanceType<T>          → factory's return │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  const makeService = factory(Service);       │
│  const s = makeService('/api', 5000);        │
│                                              │
│  s: Service                                  │
│                                              │
└──────────────────────────────────────────────┘

Visual: Method Extraction

┌──────────────────────────────────────────────┐
│  class UserService {                         │
│    getUser(id: number): Promise<User> { }    │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  UserService['getUser']                      │
│  → (id: number) => Promise<User>             │
│                                              │
└──────────────────────────────────────────────┘
       │
       ├──────► Parameters<...>
       │        → [id: number]
       │
       └──────► ReturnType<...>
                → Promise<User>
                │
                │  Awaited
                ▼
                User

Visual: Decision Flow

┌──────────────────────────────────────────────┐
│  Need a function's return type?              │
│       └── ReturnType<typeof fn>              │
│                                              │
│  Need a method's return type?                │
│       └── ReturnType<Class['method']>        │
│                                              │
│  Need the resolved async value?              │
│       └── Awaited<ReturnType<...>>           │
│                                              │
│  Need parameters?                            │
│       └── Parameters<typeof fn>              │
│                                              │
│  Need constructor parameters?                │
│       └── ConstructorParameters<typeof C>    │
│                                              │
│  Need an instance type?                      │
│       └── InstanceType<typeof C>             │
│                                              │
│  Writing a wrapper?                          │
│       └── Use Parameters<T> and ReturnType<T>│
│                                              │
└──────────────────────────────────────────────┘

Summary

Utility	Extracts
`ReturnType<T>`	Function’s return type
`Parameters<T>`	Function’s parameter tuple
`Awaited<T>`	Resolved value of a promise
`InstanceType<T>`	Instance type of a constructor

Key takeaways:

ReturnType<T> gives what a function returns — the async version gives Promise<T>
Parameters<T> gives a function’s parameter tuple — index into it for one parameter
Awaited<T> unwraps promises, recursively — non-promises pass through unchanged
InstanceType<T> gives the instance type from a constructor type — the result of new
ConstructorParameters<T> is Parameters for constructors
All four are built on infer — a conditional type capturing a part of the function or class type
Combine Awaited<ReturnType<T>> to get the resolved value of an async function
Wrappers use Parameters<T> and ReturnType<T> to preserve a function’s signature
Factories use ConstructorParameters<T> and InstanceType<T> to type input and output
Methods are accessed via Class['method'] for both Parameters and ReturnType
Generic functions return unknown from ReturnType unless instantiated with a concrete type
Constraints — T extends (...args: any) => any — keep the utilities safe

Remember: These four utilities answer the four questions you can ask about a function or class: what does it return, what does it take, what does the promise resolve to, and what does new produce? They’re all infer in different patterns. Use them to type wrappers, factories, and derived types without duplicating signatures. When the function changes, every consumer updates. That’s the value — single source of truth, derived types that follow.

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!

ReturnType<T> — the function’s return type

Parameters<T> — the function’s parameter tuple

Awaited<T> — unwrap a promise, recursively

InstanceType<T> — the constructor’s instance

Combining the four

A full example

Complete Example Session

Quick Reference

The Four Utilities

Implementations

Constraints

Related Utilities

Common Patterns

Practical Examples

Function Type Constraints

On Methods vs Functions

Generic Functions

Error Cases

Wrapper Pattern

Async Wrapper Pattern

Factory Pattern

When to Use Each

Best Practices

Common Pitfalls

Real-World Examples

1. Function return type

2. Method return type

3. Async resolved

4. Function parameters

5. Method parameters

6. First parameter

7. Class instance

8. Constructor params

9. Memoize wrapper

10. Retry wrapper

11. Timing wrapper

12. Class factory

13. Typed event handler

14. Get async value type

15. Get promise type

16. Wrapper that preserves type

17. Extract method parameters

18. Method call signature

19. Constructor type

20. Async wrapper with typed params

Visual: The Four Utilities

Visual: ReturnType

Visual: Parameters

Visual: Awaited

Visual: InstanceType

Visual: Wrapper Pattern

Visual: Async Pipeline

Visual: Factory Pattern

Visual: Method Extraction

Visual: Decision Flow

Summary

`ReturnType<T>` — the function’s return type

`Parameters<T>` — the function’s parameter tuple

`Awaited<T>` — unwrap a promise, recursively

`InstanceType<T>` — the constructor’s instance