Generic types & interfaces

One reply type for every kind of data

A shop's server answers every request the same way: a status number, like 200 for "OK", and the data you asked for. Ask for products and data is a list of products. Ask for your profile and it's one user. Here are two types for those two replies:

1type Product = { name: string; price: number };2type User = { name: string; email: string };3 4type ProductsReply = { status: number; data: Product[] };5type UserReply = { status: number; data: User };6 7const products: ProductsReply = { status: 200, data: [{ name: "Tea", price: 3 }] };8const user: UserReply = { status: 200, data: { name: "Asha", email: "asha@example.com" } };9console.log(products.data[0].name, user.data.name);

Lines 1 and 2 describe a product and a user with type, which gives a name to a type (the Type aliases and interfaces lesson covers it). Lines 4 and 5 describe the two replies. They are the same except for data: Product[] on line 4, User on line 5. Lines 7 and 8 make one reply of each, and line 9 prints Tea Asha.

A real shop has replies for orders, reviews, and coupons too. That's one more copy each time, and if the server adds a field, you change every copy. A generic type writes the reply once, with a blank where data's type goes:

1type Product = { name: string; price: number };2type User = { name: string; email: string };3 4type ApiResponse<T> = { status: number; data: T };5 6const products: ApiResponse<Product[]> = { status: 200, data: [{ name: "Tea", price: 3 }] };7const list = products.data;8//    ^?9const user: ApiResponse<User> = { status: 200, data: { name: "Asha", email: "asha@example.com" } };10const profile = user.data;11//    ^?12console.log(list[0].name, profile.name);

Line 4 has the new part: <T> after the type's name. As in the Generic functions lesson, T is a type parameter, a name that stands for a type. Here it belongs to the type, and data: T says data has whatever type T is.

Line 6 writes ApiResponse<Product[]>. The type in the angle brackets is the type argument: it fills in T, so this reply's data is a Product[]. The query on line 8 shows const list: Product[]. Line 9 fills in T with User, and line 11 shows const profile: User. There are no errors, and line 12 prints Tea Asha.

Generic type aliases: a type with a blank

A type alias gets type parameters the same way: angle brackets after its name. A sign-up form is a good place for one. Every field has a value and maybe an error message, but the values differ: the email is text, the age is a number, and a checkbox is true or false.

1type Field<T> = { value: T; error: string | null };2 3const email: Field<string> = { value: "asha@example.com", error: null };4const age: Field<number> = { value: 30, error: null };5const nextAge = age.value + 1;6//    ^?7type AgeField = Field<number>;8//   ^?9console.log(email.value, nextAge);

Line 1 says a Field<T> has a value of type T and an error that is text or null (null here means "no error"). Line 3 makes an email field, Field<string>. Line 4 makes an age field, Field<number>, so age.value is a number. Line 5 adds 1 to it, and the query on line 6 shows const nextAge: number.

Line 7 gives Field<number> a name of its own. The query on line 8 shows what TypeScript reads: { value: number; error: string | null; }. It put number everywhere line 1 says T. Line 9 prints asha@example.com 31.

Unlike a function call, a generic type in an annotation doesn't work out T for you. Leave the angle brackets out and TypeScript stops you:

1type Field<T> = { value: T; error: string | null };2 3const name: Field = { value: "Asha", error: null };4console.log(name.value);

Line 3 writes plain Field. TypeScript marks it, on purpose here: Generic type 'Field' requires 1 type argument(s) means "Field has one blank, and you didn't fill it in". The "(s)" is there because the same message is used for types with several blanks. Run it anyway and line 4 prints Asha: the types are gone by then.

Now try it yourself. Type a type argument for line 3 and watch the errors and the answer after ^? on line 5:

1type Field<T> = { value: T; error: string | null };2 3const email: Field<string> = { value: "asha@example.com", error: null };4const typed = email.value;5//    ^?6console.log(typed);

With string, the email fits. With number or boolean, the email on line 3 is the wrong kind of value, so TypeScript marks it, and line 5 still shows the type you asked for. string | null fits too, but then value may be null. Email isn't a type that exists, and empty brackets leave the blank unfilled.

An interface can only describe an object, but a type alias can name any type, so a generic alias can be a union, a type that is one of several:

1type Maybe<T> = T | null;2type OneOrMany<T> = T | T[];3 4type Tags = OneOrMany<string>;5//   ^?6function toList(tags: Tags): string[] {7  return Array.isArray(tags) ? tags : [tags];8}9 10const coupon: Maybe<string> = null;11console.log(toList("sale"), toList(["new", "sale"]), coupon);

Line 1 makes Maybe<T>: a T or null. Line 2 makes OneOrMany<T>: one T or a list of them, like a tag box that takes one tag or several. Line 4 fills it in with string, and the query on line 5 shows type Tags = string | string[].

Lines 6 to 8 turn either kind into a list: Array.isArray checks whether tags is already one. Line 10 makes a coupon code that is Maybe<string>, so null fits. Line 11 prints [ 'sale' ] [ 'new', 'sale' ] null.

Generic interfaces

Interfaces take type parameters too, written the same way. A product list that loads one page at a time is a common use:

1interface Page<T> {2  items: T[];3  page: number;4  hasMore: boolean;5}6 7type Product = { name: string; price: number };8 9const firstPage: Page<Product> = {10  items: [{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }],11  page: 1,12  hasMore: true,13};14const shown = firstPage.items;15//    ^?16console.log(shown.length, firstPage.hasMore);

Lines 1 to 5 declare Page<T>: a list of T items, the page number, and whether there are more pages. Line 9 says firstPage is a Page<Product>, so every item must be a product. Line 14 reads the items, and the query on line 15 shows const shown: Product[]. Line 16 prints 2 true.

Generic types and generic functions work well together. A function can take a Page<T> with its own type parameter, and TypeScript fills in that T from the page you pass:

1interface Page<T> {2  items: T[];3  page: number;4  hasMore: boolean;5}6 7function nextPage<T>(current: Page<T>, items: T[]): Page<T> {8  return { items, page: current.page + 1, hasMore: items.length > 0 };9}10 11const sizes: Page<string> = { items: ["S", "M"], page: 1, hasMore: true };12const more = nextPage(sizes, ["L"]);13//    ^?14const broken = nextPage(sizes, [42]);15console.log(more.page, more.items);

Line 7 declares nextPage<T>. It takes the current page and the new items, and gives back the next page with the same T. Line 11 makes a page of sizes, a Page<string>. Line 12 passes it with ["L"], so T is string, and line 13 shows const more: Page<string>.

Line 14 passes the same page with [42]. The page says T is string, so the new items must be text too. TypeScript marks the 42: Type 'number' is not assignable to type 'string' means "this list should hold text, and 42 is a number". Line 15 prints 2 [ 'L' ].

The table below compares the two ways to write a generic type. Read each row as a question, then each answer.

For an object shape, either works, and you use them the same way. Pick the one your project already uses.

Default type parameters

Most fields on a form hold text. Writing Field<string> every time is repetitive. A default type parameter says which type to use when you leave the type argument out. You write it with =, like a default value for a function parameter:

1type Field<T = string> = { value: T; error: string | null };2 3const name: Field = { value: "Asha", error: null };4//    ^?5const age: Field<number> = { value: 30, error: null };6//    ^?7console.log(name.value, age.value);

Line 1 says T = string: when nothing fills in T, use string. Line 3 writes plain Field, and the query on line 4 shows const name: Field<string>. Line 5 writes Field<number>, and line 6 shows Field<number>: a type argument you write wins over the default. Line 7 prints Asha 30.

Press the buttons to write line 1 three ways, and watch line 3:

1type Field<T> = { value: T; error: string | null };2 3const name: Field = { value: "Asha", error: null };4//    ^?5const age: Field<number> = { value: 30, error: null };6console.log(name.value, age.value);

With No default, plain Field is an error, as before. Default string fixes it. Default number shows that the default is a type, not a guess: plain Field now means Field<number>, and the text "Asha" doesn't fit. Line 5 never changes, because it writes its own type argument.

A type can have several type parameters, separated by commas, and only some of them need defaults:

1type Field<Value, Problem = string> = { value: Value; error: Problem | null };2 3const email: Field<string> = { value: "asha@", error: "Add the part after @" };4const password: Field<string, string[]> = { value: "abc", error: ["Too short", "Add a number"] };5type PasswordField = Field<string, string[]>;6//   ^?7console.log(email.error, password.error?.length);

Line 1 names two type parameters: Value for the value and Problem for the error, which is text unless you say otherwise. Line 3 fills in only Value, so the email's error is text. Line 4 fills in both: a password field whose error is a list of problems. Line 5 names that type, and the query on line 6 shows it with error: string[] | null. Line 7 prints Add the part after @ 2: the email's message and the number of password problems. The ?. reads length only when error isn't null.

Type parameters with defaults go last. Otherwise, a single type argument like Field<string> would be unclear:

1type Field<Problem = string, Value> = { value: Value; error: Problem | null };

TypeScript says Required type parameters may not follow optional type parameters. A required type parameter has no default, so it must be filled in; an optional one has a default. Here Value is required and comes after Problem, which is optional. Swap them, as in the example before, and the error is gone.

Generic functions can have defaults too. A default is used when TypeScript has nothing to fill in T from:

1function emptyList<T = string>(): T[] {2  return [];3}4 5const tags = emptyList();6//    ^?7const prices = emptyList<number>();8//    ^?9console.log(tags, prices);

Line 1 says T = string. Line 5 calls emptyList() with no arguments, so nothing tells TypeScript what T is, and line 6 shows const tags: string[]. Without the default it would be unknown[], as in the Generic functions lesson. Line 7 writes <number>, and line 8 shows const prices: number[]. Line 9 prints [] [].

Generics you already use: Array, Map, Promise

You have been using generic types since the Arrays and tuples lesson. TypeScript's own types for arrays, Maps, Sets, and promises are generic, written the same way as yours:

1const tags: Array<string> = ["new", "sale"];2const quantities = new Map<string, number>();3quantities.set("Tea", 2);4const teaCount = quantities.get("Tea");5//    ^?6const sizes = new Set<string>(["S", "M"]);7console.log(tags.length, teaCount, sizes.has("M"));

Line 1 writes Array<string>, the same type as string[]. Line 2 makes a Map, which stores values by key (the Map and Set lesson covers it). Its two type arguments say the keys are text and the values are numbers. Line 3 stores 2 for Tea. Line 4 reads it back, and the query on line 5 shows number | undefined: get gives back undefined for a key that isn't there. Line 6 makes a Set of sizes. Line 7 prints 2 2 true.

The type arguments are checked like any other type:

1const quantities = new Map<string, number>();2quantities.set("Tea", 2);3quantities.set("Cake", "1");4console.log(quantities.get("Cake"));

Line 3 stores the text "1". TypeScript says Argument of type 'string' is not assignable to parameter of type 'number': the Map's values must be numbers. Run it anyway and line 4 prints 1, but it's text, and adding it to other quantities would join them.

Promise<T> is the type of a promise: a value that arrives later. T is the type of what it will hold. An async function always gives back a promise (see async and await):

1type User = { name: string; email: string };2 3async function loadUser(): Promise<User> {4  return { name: "Asha", email: "asha@example.com" };5}6 7const pending = loadUser();8//    ^?9pending.then((user) => console.log(user.name));10//            ^?

Lines 3 to 5 declare loadUser, an async function. It returns a user object, but its return type is Promise<User>, because an async function wraps what it returns in a promise. Line 7 calls it. The query on line 8 shows const pending: Promise<User>: not a user yet, but a promise of one. Line 9 uses then, which calls a function with what the promise holds when it's ready. The query on line 10 shows (parameter) user: User: TypeScript took User out of Promise<User>. It prints Asha.

Press the buttons to read the user three ways on line 8:

1type User = { name: string; email: string };2 3async function loadUser(): Promise<User> {4  return { name: "Asha", email: "asha@example.com" };5}6 7async function showName() {8  console.log(loadUser().name);9}10showName();

Read it right away treats the promise as if it were the user, and TypeScript stops it. await it and Use then both wait for the user. The type argument of Promise<User> is what lets TypeScript know that what comes out is a User.

Generic types can go inside each other. A function that loads products from the server gives back a promise of a reply of a list:

1type Product = { name: string; price: number };2type ApiResponse<T> = { status: number; data: T };3 4async function loadProducts(): Promise<ApiResponse<Product[]>> {5  return { status: 200, data: [{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }] };6}7 8async function showCount() {9  const reply = await loadProducts();10  //    ^?11  console.log(reply.data.length);12}13showCount();

Line 4 says loadProducts gives back Promise<ApiResponse<Product[]>>. Read it from the outside in: a promise, holding an ApiResponse, whose data is a Product[]. Line 9 uses await, which opens the promise, and the query on line 10 shows const reply: ApiResponse<Product[]>. Line 11 reads reply.data.length and prints 2. Line 13 calls the function.

The table below lists the built-in generic types you'll meet most. Read each row as: the type, what fills in its blanks, and an example.

Loading states for any page

Every page that loads data shows one of three things: a loading message, an error, or the data. A product list and a profile page load different data, but the three states are the same. One generic type describes them all:

1type Product = { name: string; price: number };2type User = { name: string; email: string };3 4type LoadState<T> =5  | { status: "loading" }6  | { status: "error"; message: string }7  | { status: "done"; data: T };8 9function productsText(state: LoadState<Product[]>) {10  if (state.status === "loading") return "Loading...";11  if (state.status === "error") return "Sorry: " + state.message;12  const list = state.data;13  //    ^?14  return list.length + " products";15}16 17function profileText(state: LoadState<User>) {18  if (state.status !== "done") return "No profile yet";19  return "Hi " + state.data.name;20}21 22console.log(productsText({ status: "done", data: [{ name: "Tea", price: 3 }] }));23console.log(productsText({ status: "error", message: "Offline" }));24console.log(profileText({ status: "done", data: { name: "Asha", email: "asha@example.com" } }));

Lines 4 to 7 declare LoadState<T>: a union of three object types, told apart by status (the Discriminated unions lesson covers this pattern). Only the "done" state has data, and its type is T.

• Line 9 takes a LoadState<Product[]>. Lines 10 and 11 handle loading and errors. After them, only "done" is left, so line 12 may read state.data, and line 13 shows const list: Product[].
• Line 17 takes a LoadState<User>. After the check on line 18, line 19 reads state.data.name, because data is a User here.
• Lines 22 to 24 print 1 products, Sorry: Offline, and Hi Asha.

The same type also stops you from reading data before it has loaded:

1type User = { name: string; email: string };2 3type LoadState<T> =4  | { status: "loading" }5  | { status: "error"; message: string }6  | { status: "done"; data: T };7 8function profileText(state: LoadState<User>) {9  return "Hi " + state.data.name;10}11 12console.log(profileText({ status: "loading" }));

Line 9 reads state.data without checking status first. TypeScript says Property 'data' does not exist on type 'LoadState<User>': the loading and error states have no data. Line 12 passes a loading state, and when the code runs it stops with a TypeError.

Common mix-ups

A type argument tells TypeScript what you expect. It doesn't check data that arrives while the page runs:

1type ApiResponse<T> = { status: number; data: T };2 3const text = '{ "status": 200, "data": "7" }';4const reply: ApiResponse<number> = JSON.parse(text);5console.log(reply.data + 1);

Line 3 is a reply as the server sent it, with data as the text "7". Line 4 parses it with JSON.parse (see the JSON lesson) and says it's an ApiResponse<number>. JSON.parse can give back anything, so TypeScript trusts you, and there are no errors. Line 5 prints 71, because "7" + 1 joins text.

The table below shows when you write a type argument. Read each row as: this code, do you need one, and why.

• "TypeScript fills in a generic type's argument from the value, like it does for a function." No. In an annotation like const name: Field, you write the type argument, or the type parameter needs a default.
• "ApiResponse<number> checks the server's reply." No. Types are removed before the code runs. The reply with the text "7" got through and printed 71.
• "A default type parameter changes to match the value." No. T = string means plain Field is always Field<string>. For a number, write Field<number>.
• "A Promise<User> is a user." No. It's a promise that will hold one. Use await or then to get the user out.
• "The T in one generic type is the same T as in another." No. Each declaration has its own type parameters. T in Field<T> and T in Page<T> are unrelated, like two functions that both have a parameter called value.
• "Generic interfaces and generic type aliases work differently." No. For object shapes, you declare and use them the same way. Only a type alias can be a union, like Maybe<T>.

Practice exercises

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

1type Field<T> = { value: T; error: string | null };2 3const quantity: Field<number> = { value: 2, error: null };4const count = quantity.value;

1type Field<T> = { value: T; error: string | null };2 3const quantity: Field<number> = { value: 2, error: null };4const count = quantity.value;5//    ^?

type Field<T> = { value: T; error: string | null };

const email: Field<string> = { value: "asha@example.com", error: null };
const age: Field<number> = { value: "30", error: null };
const agree: Field<boolean> = { value: true, error: null };

1type Field<T> = { value: T; error: string | null };2 3const email: Field<string> = { value: "asha@example.com", error: null };4const age: Field<number> = { value: "30", error: null }; // line 4: "30" is text5const agree: Field<boolean> = { value: true, error: null };

1type Product = { name: string; price: number };2 3type ProductPage = { items: Product[]; page: number };4type SizePage = { items: string[]; page: number };5 6const products: ProductPage = { items: [{ name: "Tea", price: 3 }], page: 1 };7const sizes: SizePage = { items: ["S", "M", "L"], page: 2 };8console.log(products.items.length + sizes.items.length);

1type Product = { name: string; price: number };2 3type Page<T> = { items: T[]; page: number };4 5const products: Page<Product> = { items: [{ name: "Tea", price: 3 }], page: 1 };6const sizes: Page<string> = { items: ["S", "M", "L"], page: 2 };7console.log(products.items.length + sizes.items.length);

1type User = { name: string; email: string };2type ApiResponse<T> = { status: number; data: T };3 4const reply: ApiResponse = { status: 200, data: { name: "Asha", email: "asha@example.com" } };5console.log(reply.data.name);

1type User = { name: string; email: string };2type ApiResponse<T> = { status: number; data: T };3 4const reply: ApiResponse<User> = { status: 200, data: { name: "Asha", email: "asha@example.com" } };5console.log(reply.data.name);

1type Field<T> = { value: T; error: string | null };2 3const firstName: Field = { value: "Asha", error: null };4const lastName: Field = { value: "Rao", error: null };5const age: Field<number> = { value: 30, error: null };6console.log(firstName.value, lastName.value, age.value);

1type Field<T = string> = { value: T; error: string | null };2 3const firstName: Field = { value: "Asha", error: null };4const lastName: Field = { value: "Rao", error: null };5const age: Field<number> = { value: 30, error: null };6console.log(firstName.value, lastName.value, age.value);

1const quantities = new Map();2quantities.set("Tea", 2);3quantities.set("Cake", "1");4 5let total = 0;6for (const count of quantities.values()) {7  total += count;8}9console.log(total);

1const quantities = new Map<string, number>();2quantities.set("Tea", 2);3quantities.set("Cake", 1);4 5let total = 0;6for (const count of quantities.values()) {7  total += count;8}9console.log(total);

Check your understanding

For each question, find each generic type's blanks and what fills them: a type argument you wrote, or a default. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A generic type is a type alias or an interface with a type parameter, like ApiResponse<T>. Write it once, instead of one copy per kind of data.
• Each use fills in T with a type argument, like ApiResponse<User>, and TypeScript reads the type with T replaced.
• In an annotation, you write the type argument. TypeScript doesn't work it out from the value.
• A default, like <T = string>, is used when you leave the type argument out. A type argument you write wins. Type parameters with defaults go last.
• Array<T>, Map<K, V>, Set<T>, and Promise<T> are generic types too. Read nested ones, like Promise<ApiResponse<Product[]>>, from the outside in.
• A type argument is something you tell TypeScript. Data that arrives while the page runs isn't checked against it.

Coming next: Generic classes. It puts type parameters on classes, for a typed stack or cache that keeps its item type.