ReturnType, Awaited & more

New types from the types you have

A shop tracks every order with a status: pending, paid, shipped, or cancelled. A reminder email should only go out for orders that are still open, pending or paid. You could write a second list of statuses by hand, but then two lists must be kept the same forever. TypeScript can make the new type from the one you already have:

1type OrderStatus = "pending" | "paid" | "shipped" | "cancelled";2type OpenStatus = Exclude<OrderStatus, "shipped" | "cancelled">;3//   ^?4 5function remindShopper(status: OpenStatus) {6  console.log(`Your order is ${status}`);7}8remindShopper("paid");9remindShopper("cancelled");

Line 1 lists the four statuses as a union: a type that allows one of several values, written with | between them (the Union types lesson covers them). Each value in the list is called a member. Line 2 makes OpenStatus with Exclude, which takes two types in angle brackets: the union to start from, and the members to take out. The query on line 3 shows the result: type OpenStatus = "pending" | "paid".

Lines 5 to 7 are a function that only takes an open status. Line 8 passes "paid", which is fine. Line 9 passes "cancelled", and TypeScript marks it, on purpose:

• Argument of type '"cancelled"' is not assignable to parameter of type 'OpenStatus' means ""cancelled" isn't one of the values OpenStatus allows". An argument is a value you pass in a call.

When the code runs, it prints Your order is paid and then Your order is cancelled: types are removed before the code runs, so the error is a warning for you, not a stop.

Exclude is one of TypeScript's utility types: type helpers that come with TypeScript, ready to use in any file. The Partial, Pick, Omit & friends lesson covered the ones for object types. This lesson covers six more, for unions, functions, and promises:

• Exclude and Extract take members out of a union, or keep only some.
• NonNullable takes out null and undefined.
• ReturnType and Parameters read what a function gives back and what it takes.
• Awaited gives the value inside a promise.

Filtering a union with Exclude and Extract

Exclude<Union, Remove> goes through Union one member at a time. For each member, it asks: does this fit Remove? "Fits" means the value would be allowed where Remove is the type; TypeScript's word for it is assignable. Every member that fits is taken out. Type your own second type on line 3, and watch the answer after ^? on line 4:

1type OrderStatus = "pending" | "paid" | "shipped" | "cancelled";2 3type Result = Exclude<OrderStatus, "cancelled">;4//   ^?5const next: Result = "paid";6console.log(next);

With "shipped" | "cancelled", two statuses are left, as in the overview. With "paid", line 5 gets an error, because "paid" was taken out. With "canceled", spelled with one l, nothing is taken out and TypeScript says nothing: Exclude doesn't check that the second type is part of the union. With string, every status fits and is taken out, so nothing is left. TypeScript calls that never, the type with no values at all. cancelled without quotes gets Cannot find name 'cancelled', because a name without quotes means a type with that name.

Extract<Union, Keep> is the opposite. It keeps only the members that fit Keep. It's most useful with a union of object types, like the events a shopping cart sends when something changes:

1type CartEvent =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string }4  | { type: "clear" };5 6type AddEvent = Extract<CartEvent, { type: "add" }>;7//   ^?8type OtherEvent = Exclude<CartEvent, { type: "add" }>;9//   ^?10 11function showAdded(event: AddEvent) {12  console.log(`Added ${event.name} for $${event.price}`);13}14showAdded({ type: "add", name: "Tea", price: 3 });

Lines 1 to 4 describe three kinds of event. Each has a type property that says which kind it is (the Discriminated unions lesson covers this pattern). Line 6 keeps the members that fit { type: "add" }. An object type fits when it has at least those properties, so only the add event does. The query on line 7 shows it, with its name and price too.

Line 8 uses Exclude with the same check, and the query on line 9 shows the other two events. Lines 11 to 13 are a function that only takes add events, so it can read event.price: every AddEvent has one. Line 14 prints Added Tea for $3.

The table below puts the two helpers side by side. Read each row as: what you write, which members it keeps, and the result.

Removing null and undefined with NonNullable

A value that might be missing often has a type like string | null. null means "nothing here, on purpose", and undefined means "not set" (see null and undefined). NonNullable<T> takes both out of T. Here a profile form has an optional nickname:

1type ProfileForm = {2  name: string;3  nickname: string | null;4};5 6type Nickname = NonNullable<ProfileForm["nickname"]>;7//   ^?8 9function showBadge(nickname: Nickname) {10  console.log(`Hi, ${nickname.toUpperCase()}!`);11}12 13const form: ProfileForm = { name: "Asha", nickname: "Ash" };14if (form.nickname) showBadge(form.nickname);15showBadge(form.nickname);

Lines 1 to 4 describe the form. The nickname can be left empty, so it's string | null. On line 6, ProfileForm["nickname"] means "the type of the nickname property in ProfileForm", which is string | null. NonNullable takes the null out, and the query on line 7 shows type Nickname = string.

Lines 9 to 11 show a badge. Line 10 can call toUpperCase, because a Nickname is always text. Line 13 fills in the form. Line 14 checks the nickname first: inside the if, it can't be null (the Narrowing lesson explains this). Line 15 doesn't check, and TypeScript marks it on purpose:

• Argument of type 'string | null' is not assignable to parameter of type 'string' means "this nickname might be null, and the badge needs text".

This form has a nickname, so the code prints Hi, ASH! twice. With nickname: null, line 15 would throw a TypeError when it runs, because null has no toUpperCase.

NonNullable is most useful with a type parameter, where you don't know the exact type ahead of time (see Generic functions). This helper makes sure a value is there:

1function requireValue<T>(value: T, label: string): NonNullable<T> {2  if (value === null || value === undefined) {3    throw new Error(`${label} is missing`);4  }5  return value;6}7 8const params = new URLSearchParams("city=Pune");9const savedCity = params.get("city");10//    ^?11const city = requireValue(savedCity, "city");12//    ^?13console.log(city.toUpperCase());

Line 1 says requireValue takes a value of any type T and a label, and gives back NonNullable<T>. Lines 2 to 4 throw an error when the value is null or undefined, so line 5 only runs with a real value, and TypeScript knows it. That's why return value fits NonNullable<T>.

Line 8 reads the part of a web address after the ?, here city=Pune, with URLSearchParams. Line 9 asks for the city. The query on line 10 shows string | null, because an address might not have one. Line 11 passes it through requireValue, and the query on line 12 shows const city: string. Line 13 prints PUNE.

A function's types with ReturnType and Parameters

The next two helpers read a function's type. They are the built-in versions of the ReturnOf and ParamsOf you wrote in The infer keyword. A helper takes a type, and a function is a value. The word typeof, written where a type goes, turns a value into its type (keyof & typeof covers it). typeof createCartItem means "the type of the function createCartItem": what it takes and what it gives back.

1function createCartItem(name: string, price: number, quantity = 1) {2  return { name, price, quantity };3}4 5type CartItem = ReturnType<typeof createCartItem>;6//   ^?7type ItemArgs = Parameters<typeof createCartItem>;8//   ^?9 10const args: ItemArgs = ["Cake", 4];11const cake: CartItem = createCartItem(...args);12console.log(cake);

Line 1 makes a cart item from a name, a price, and a quantity. The quantity is 1 unless you pass one: a default value (see Parameters). Line 2 returns the three as an object. TypeScript works out what the function returns, so nobody wrote that type down.

Line 5 names it with ReturnType, and the query on line 6 shows { name: string; price: number; quantity: number; }. Line 7 uses Parameters. The query on line 8 shows a tuple, a list with a fixed length and a type for each place: [name: string, price: number, quantity?: number | undefined]. The ? means the quantity may be left out.

Line 10 makes a list of arguments that fits ItemArgs, and line 11 spreads them into the call with ... (see Spread and rest). Line 12 prints { name: 'Cake', price: 4, quantity: 1 }.

Press the buttons to write line 5 five ways, and watch the answer after ^? and the list under the code:

1function createCartItem(name: string, price: number, quantity = 1) {2  return { name, price, quantity };3}4 5type Result = ReturnType<typeof createCartItem>;6//   ^?

ReturnType and Parameters give the two types from the picture. Parameters, item 0 adds [0], which reads the first place of the tuple: string, the name. Without typeof gets 'createCartItem' refers to a value, but is being used as a type here, and the message ends with the fix, Did you mean 'typeof createCartItem'? A string gets Type 'string' does not satisfy the constraint '(...args: any) => any'. (...args: any) => any is how TypeScript writes "any function", and ReturnType only takes those. In both error cases, the query shows any: TypeScript gave up on the type.

These two helpers are most useful when you wrap a function: you write a new function that does something extra, then calls the original. Here, a shop logs every coupon a shopper tries:

1function applyCoupon(total: number, code: string) {2  return code === "SAVE5" ? total - 5 : total;3}4 5function trackCoupon(6  ...args: Parameters<typeof applyCoupon>7): ReturnType<typeof applyCoupon> {8  console.log("Coupon tried:", args[1]);9  return applyCoupon(...args);10}11 12console.log(trackCoupon(20, "SAVE5"));13trackCoupon(20);

Lines 1 to 3 apply a coupon: SAVE5 takes 5 off the total. Lines 5 to 10 wrap it. Line 6 collects every argument into the list args, typed Parameters<typeof applyCoupon>, so args is [total: number, code: string]. Line 7 says trackCoupon returns what applyCoupon returns, a number. Line 8 logs the code, and line 9 spreads args into applyCoupon.

Line 12 prints Coupon tried: SAVE5 and then 15. Line 13 forgets the code, and TypeScript marks it on purpose: Expected 2 arguments, but got 1, the same check a call to applyCoupon gets. It still runs and prints Coupon tried: undefined. If applyCoupon later takes a third argument, trackCoupon follows without an edit.

Unwrapping promises with Awaited

An async function always returns a promise: a value that arrives later (see Promises and async and await). So ReturnType of an async function is a promise type, not the data inside it. Press the buttons to name a loaded cart three ways:

1async function fetchCart() {2  return { items: ["Tea", "Cake"], total: 7 };3}4 5type Cart = ReturnType<typeof fetchCart>;6//   ^?7 8function cartSummary(cart: Cart) {9  return `${cart.items.length} items, $${cart.total}`;10}11 12fetchCart().then((cart) => console.log(cartSummary(cart)));

With ReturnType only, the query on line 6 shows Promise<{ items: string[]; total: number; }>. Line 9 gets Property 'items' does not exist on type 'Promise<…>' (and the same for total): a promise has no items, only the cart inside it does. Line 12 gets an error too, because .then hands cartSummary the real cart where it expects a promise.

Awaited of ReturnType unwraps the promise, and every error is gone. Awaited of the function unwraps nothing: typeof fetchCart is the function, not a promise, so Awaited gives it back as it is, and lines 9 and 12 get errors again. In every case the code prints 2 items, $7, because the types are removed before it runs.

Awaited follows the same rules as await. Like UnwrapAll from the infer lesson, it keeps unwrapping, and it leaves other types alone:

1type Nested = Awaited<Promise<Promise<number>>>;2//   ^?3type Plain = Awaited<string>;4//   ^?5type Mixed = Awaited<boolean | Promise<number>>;6//   ^?

Line 1 is a promise of a promise of a number. The query on line 2 shows number: Awaited unwraps until no promise is left. Line 3 gives it string, which isn't a promise, so the query on line 4 shows string. Line 5 is a union, and Awaited works on each member: boolean stays, and Promise<number> becomes number. The query on line 6 shows number | boolean.

For a variable, you rarely write Awaited yourself, because await already gives the unwrapped type:

1async function fetchCart() {2  return { items: ["Tea", "Cake"], total: 7 };3}4 5async function showCart() {6  const cart = await fetchCart();7  //    ^?8  console.log(`${cart.items.length} items`);9}10showCart();

Line 6 waits for fetchCart's promise. The query on line 7 shows cart is the cart itself, { items: string[]; total: number; }. Line 8 prints 2 items. You need Awaited when you want the name of that type without awaiting: for a function's parameter, like cartSummary(cart: Cart) in the playground, or for a variable you fill in later.

Shipping quotes on a checkout page

A checkout page asks a server what shipping costs. The function that asks is written once, and the page names its types from it:

1type Speed = "standard" | "express" | "drone";2 3async function quoteShipping(speed: Speed, weightKg: number) {4  const pricePerKg = { standard: 3, express: 8, drone: 15 };5  return { speed, price: pricePerKg[speed] * weightKg, days: speed === "standard" ? 4 : 2 };6}7 8type Quote = Awaited<ReturnType<typeof quoteShipping>>;9//   ^?10type OfferedSpeed = Exclude<Parameters<typeof quoteShipping>[0], "drone">;11//   ^?12 13function showQuote(quote: Quote) {14  console.log(`${quote.speed}: $${quote.price} in ${quote.days} days`);15}16 17const offered: OfferedSpeed[] = ["standard", "express"];18for (const speed of offered) {19  quoteShipping(speed, 2).then(showQuote);20}

Line 1 lists three delivery speeds. Lines 3 to 6 ask for a quote: line 4 has a price per kilogram for each speed, and line 5 returns the speed, the price for the weight, and the days it takes. It's async, as a real request to a server would be.

Line 8 names the quote with Awaited of ReturnType, and the query on line 9 shows its three properties. Line 10 takes the first parameter's type, Speed, and excludes "drone", because this shop doesn't deliver by drone yet. The query on line 11 shows "standard" | "express".

Lines 13 to 15 print a quote. Line 17 lists the speeds the page offers; "drone" there would be an error. Lines 18 to 20 ask for a 2-kilogram quote at each speed. The code prints standard: $6 in 4 days and then express: $16 in 2 days. No type was written twice: add a speed or a property to quoteShipping, and Quote and OfferedSpeed follow.

The table below sums up the six helpers. Read each row as: the helper, what you give it, and what you get back.

Common mix-ups

Exclude and Omit both take something out, so they're easy to swap. Omit (from the Partial, Pick, Omit & friends lesson) takes properties out of an object type:

1type Order = { id: number; total: number; coupon: string | null };2 3type WithoutCoupon = Omit<Order, "coupon">;4//   ^?5type NothingRemoved = Exclude<Order, "coupon">;6//   ^?

Line 1 describes an order. Line 3 uses Omit to take out the coupon property, and the query on line 4 shows the id and total that are left. Line 5 tries Exclude instead. Order isn't a union of names; it's one object type, and it doesn't fit "coupon", so nothing is taken out. The query on line 6 shows all three properties, and no error warns you.

The table below compares them. Read each row as: what you write, what it works on, and what you get.

NonNullable only works on the type you give it, not on the properties inside an object:

1type Profile = { name: string; nickname: string | null };2 3type Loaded = NonNullable<Profile | null>;4//   ^?5type Nickname = Loaded["nickname"];6//   ^?

Line 3 takes the null out of Profile | null, and the query on line 4 shows a profile. Line 5 reads its nickname property's type, and the query on line 6 still shows string | null.

• "Exclude tells me when I misspell a member." No. Exclude<OrderStatus, "canceled"> takes out nothing and reports nothing. Check the result with ^? or by hovering.
• "ReturnType<createCartItem> works." No. A function's name is a value. In a type, write typeof createCartItem.
• "ReturnType of an async function is its data." No. It's a promise of the data. Wrap it: Awaited<ReturnType<typeof fetchCart>>.
• "NonNullable removes null everywhere inside a type." No. It removes null and undefined from the type itself, not from its properties.
• "Exclude and Omit do the same job." No. Exclude filters a union. Omit removes properties from an object type.
• "Awaited waits for the promise." No. Like every type, it's removed before the code runs. It only names the type the promise finishes with; await does the waiting.

Practice exercises

Each exercise is TypeScript. To change the starter code, press Edit & run: the errors and ^? answers update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1type Payment = "card" | "cash" | "voucher" | "crypto";2type ShopPayment = Exclude<Payment, "voucher" | "crypto">;

1type Payment = "card" | "cash" | "voucher" | "crypto";2type ShopPayment = Exclude<Payment, "voucher" | "crypto">;3//   ^?

function loadUser(id: number) {
  return { id, name: "Asha" };
}

type User = ReturnType<loadUser>;

1function loadUser(id: number) {2  return { id, name: "Asha" };3}4 5type User = ReturnType<typeof loadUser>;6//   ^?

1type CartEvent =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string };4 5type RemoveEvent = CartEvent;6 7function logRemove(event: RemoveEvent) {8  console.log(`Removed ${event.name}`);9}10 11logRemove({ type: "remove", name: "Cake" });12logRemove({ type: "add", name: "Tea", price: 3 });

1type CartEvent =2  | { type: "add"; name: string; price: number }3  | { type: "remove"; name: string };4 5type RemoveEvent = Extract<CartEvent, { type: "remove" }>;6 7function logRemove(event: RemoveEvent) {8  console.log(`Removed ${event.name}`);9}10 11logRemove({ type: "remove", name: "Cake" });12logRemove({ type: "add", name: "Tea", price: 3 });

1type Profile = { name: string; nickname: string | null };2 3function greet(nickname: Profile["nickname"]) {4  console.log(`Hi, ${nickname.toUpperCase()}!`);5}6 7const asha: Profile = { name: "Asha", nickname: "Ash" };8greet(asha.nickname);

1type Profile = { name: string; nickname: string | null };2 3function greet(nickname: NonNullable<Profile["nickname"]>) {4  console.log(`Hi, ${nickname.toUpperCase()}!`);5}6 7const asha: Profile = { name: "Asha", nickname: "Ash" };8if (asha.nickname) greet(asha.nickname);

1async function fetchProducts(category: "tea" | "cake") {2  return [{ name: "Green tea", price: 3, category }];3}4 5type Product = ReturnType<typeof fetchProducts>;6 7function label(product: Product) {8  return `${product.name}: $${product.price}`;9}10 11fetchProducts("tea").then((products) => console.log(label(products[0])));

1async function fetchProducts(category: "tea" | "cake") {2  return [{ name: "Green tea", price: 3, category }];3}4 5type Product = Awaited<ReturnType<typeof fetchProducts>>[number];6//   ^?7 8function label(product: Product) {9  return `${product.name}: $${product.price}`;10}11 12fetchProducts("tea").then((products) => console.log(label(products[0])));

1function applyCoupon(total: number, code: string) {2  return code === "SAVE5" ? total - 5 : total;3}4 5function withLog(...args: any[]): any {6  console.log("applyCoupon", args.join(", "));7  return applyCoupon(...args);8}9 10const total = withLog(20, "SAVE5");11console.log(total);

1function applyCoupon(total: number, code: string) {2  return code === "SAVE5" ? total - 5 : total;3}4 5function withLog(6  ...args: Parameters<typeof applyCoupon>7): ReturnType<typeof applyCoupon> {8  console.log("applyCoupon", args.join(", "));9  return applyCoupon(...args);10}11 12const total = withLog(20, "SAVE5");13//    ^?14console.log(total);

Check your understanding

For each question, work out the helper's result one step at a time, from the inside out. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Exclude<Union, Remove> takes out the members that fit Remove. Extract<Union, Keep> keeps only the members that fit Keep.
• Neither one warns you when the second type matches nothing, so check the result.
• NonNullable<T> removes null and undefined from T itself, not from its properties.
• ReturnType and Parameters read a function's type, which you get with typeof: ReturnType<typeof createCartItem>.
• Awaited unwraps promises all the way. For an async function, write Awaited<ReturnType<typeof fetchCart>>.
• Types made this way follow the type or function they come from, so you never keep two copies in step by hand.

Coming next: Writing your own utility types. It rebuilds Partial and Pick from scratch, then writes helpers of your own, like a DeepPartial for settings with objects inside.