Generics, just enough

Think of a courier. You hand over a parcel, and they deliver it. They don't open it. They don't care whether it is sweets or a phone. The courier works for every parcel.

But here is the clever part. When the parcel arrives, the receiver knows what is in it. If you sent laddoos, laddoos arrive. The courier never turned them into something else.

Now think about how you would write that as a function. It takes a thing and gives the same thing back. In JavaScript that is easy, because JavaScript doesn't track what is inside. In TypeScript there is a problem. If you label the function "takes a number", it can't carry sweets. If you label it "takes anything", the receiver no longer knows what arrived.

Generics solve this. A generic function has a type parameter: a stand-in name for "whatever kind you give me". By convention it is called T, short for "type". The function says "I take a T and give back that same T". Then each call fills in the blank.

You have already met generics. string[] is "a list of string", and Array<string> is the same thing written the long way. This lesson shows how to write your own, and stops there. Generics can get deep, and you need only a little of them.

Remember: a generic is a function or type with a blank for the kind. The blank, called a type parameter, is filled in from what you pass.

A JavaScript courier is one line.

function deliver(parcel) {  return parcel;}const sweets = deliver("laddoo");const count = deliver(42);console.log(sweets.toUpperCase());console.log(count + 1);

LADDOO
43

It works for text and for numbers. Nothing stops it, and nothing tells the receiver what came out. That matters with a function like first, which hands back the first item of a list.

function first(items) {  return items[0];}const firstScore = first([90, 85, 72]);const firstName = first(["Asha", "Ravi"]);console.log(firstScore);console.log(firstScore.toUpperCase());

90
TypeError: firstScore.toUpperCase is not a function

The first score is a number, and we asked it to shout. JavaScript didn't know the list held numbers, so it didn't warn us. It found out when the line ran.

Remember: a plain JavaScript function works for every kind of input, but its output is a mystery until the code runs.

First, the cheap way out. You could label the courier any, which switches the checker off for that value.

function deliverAny(parcel: any): any {  return parcel;}const count = deliverAny(42);// No error here, and none for count.toUpperCase() either: any switches the checker off.console.log(count + 1);

It compiles, and it also compiles when you call count.toUpperCase() on a number. The parcel goes in with a label and comes out with none. That is the problem generics solve.

Here is the courier with a type parameter. The <T> after the name declares the blank. Then parcel: T says the input is a T, and : T after the brackets says the output is the same T.

function deliver(parcel) {  return parcel;}const sweets = deliver("laddoo");const count = deliver(42);console.log(sweets.toUpperCase());console.log(count + 1);

function deliver<T>(parcel: T): T {  return parcel;}const sweets = deliver("laddoo");const count = deliver(42);console.log(sweets.toUpperCase());console.log(count + 1);

TypeScript fills in T for you from what you pass. deliver("laddoo") gives back text, so sweets.toUpperCase() is allowed. deliver(42) gives back a number, so count + 1 is fine. You never wrote <string> or <number>. The checker worked it out, which is called inference (guessing the type from the code), the same idea as lesson 2.

Now first. The input is a list of T, written T[], and the output is a T or undefined, because an empty list has no first item.

function first(items) {  return items[0];}const firstScore = first([90, 85, 72]);const firstName = first(["Asha", "Ravi"]);console.log(firstScore);console.log(firstScore.toUpperCase());

function first<T>(items: T[]): T | undefined {  return items[0];}const firstScore = first([90, 85, 72]);const firstName = first(["Asha", "Ravi"]);console.log(firstScore);console.log(firstScore?.toUpperCase());

Because first is generic, the number list gives back number | undefined. The checker knows what came out. The wrong call is refused where you typed it, which is what JavaScript couldn't do.

Remember: <T> declares a blank, and T in the parameters and the result links them: whatever goes in is what comes out.

1. More than one blank. Use as many type parameters as you need, with different names. Each one is filled in separately.

function pair<A, B>(left: A, right: B): [A, B] {  return [left, right];}const entry = pair("Asha", 21);console.log(entry);

[ 'Asha', 21 ]

entry has the type [string, number]. The first slot is text, the second a number, and they never get mixed up.

You can also give the blank yourself, in angle brackets, if inference can't see enough. An empty list has nothing to learn from, so first<string>([]) says "this is a list of text".

function first<T>(items: T[]): T | undefined {  return items[0];}// Normally TypeScript works T out. You can also say it yourself.const empty = first<string>([]);console.log(empty);

undefined

2. Constraints with extends. Sometimes "any type" is too loose. A function that compares lengths needs a type that has a length. A constraint limits the blank: T extends { length: number } means "any T, as long as it has a numeric length". Text has one. So do lists.

function longest(a, b) {  return a.length >= b.length ? a : b;}console.log(longest("chai", "coffee"));console.log(longest(10, 20)); // numbers have no length, so this quietly picks 20

function longest<T extends { length: number }>(a: T, b: T): T {  return a.length >= b.length ? a : b;}console.log(longest("chai", "coffee"));console.log(longest(10, 20));

In JavaScript, longest(10, 20) quietly gives 20, because numbers have no length and both sides compare as undefined. TypeScript refuses the call, and says why. A string and a list both pass, because both have a length.

function longest<T extends { length: number }>(a: T, b: T): T {  return a.length >= b.length ? a : b;}console.log(longest("chai", "coffee"));console.log(longest([1, 2, 3], [4, 5]));

coffee
[ 1, 2, 3 ]

Notice that longest gives back the same type it was given. Pass two lists, get a list. Pass two texts, get text.

3. Keys of an object. A common trick reads a property by name. keyof T means "the names of the properties of T, as a union of exact words". So K extends keyof T says "the key must be one that this object really has", and T[K] is the type of that property.

type User = { name: string; age: number };function getField<T, K extends keyof T>(item: T, key: K): T[K] {  return item[key];}const user: User = { name: "Asha", age: 21 };console.log(getField(user, "name"));console.log(getField(user, "age"));

Asha
21

getField(user, "name") is a string and getField(user, "age") is a number. A misspelled key is caught.

type User = { name: string; age: number };function getField<T, K extends keyof T>(item: T, key: K): T[K] {  return item[key];}const user: User = { name: "Asha", age: 21 };console.log(getField(user, "agee"));

4. Generic types. Types can have blanks too. A Box<T> is a box that holds a T. It is the parcel from our picture.

type Box<T> = { value: T };function openBox<T>(box: Box<T>): T {  return box.value;}const luckyNumber: Box<number> = { value: 7 };const note: Box<string> = { value: "Call Amma" };console.log(openBox(luckyNumber) + 1);console.log(openBox(note).toUpperCase());

8
CALL AMMA

You fill in the blank when you use the type, in angle brackets: Box<number>, Box<string>. Put the wrong thing inside and the checker says so.

type Box<T> = { value: T };const luckyNumber: Box<number> = { value: "seven" };

You have been using these already. Array<number>, Map<string, number> and Promise<string> are all generic types from the language itself.

const scores: Array<number> = [90, 85];const ages = new Map<string, number>();ages.set("Asha", 21);const later: Promise<string> = Promise.resolve("done");

A type parameter can also have a default, which is used when you leave the blank empty. Result<T = string> means a plain Result is a Result<string>.

type Result<T = string> = { ok: boolean; value: T };const text: Result = { ok: true, value: "saved" };const count: Result<number> = { ok: true, value: 3 };

Remember: several blanks are fine, extends limits a blank, keyof names an object's properties, and Box<T> is a type with a blank.

A blank used once is not doing anything. If T appears only once in a function's signature, it links nothing. function log<T>(value: T): void can be written function log(value: unknown): void. A blank earns its place by connecting two things: input to output, or one parameter to another.

Generics are not a way to avoid any, or a way to hide it. Writing <T> and then casting value as T inside the function is the same as any with extra steps. The checker trusted you.

Names are only names. T is a habit. Longer names like Item or Key are fine, and clearer once you have several blanks.

Start without generics. If you only ever call the function with one type, write it for that type. Add a blank when you find yourself copying a function for a second type. Most day-to-day TypeScript uses generics that other people wrote, such as Array, Map and Promise, and writes few of its own.

Remember: a blank should link two things. If it links nothing, take it out.

Each problem starts with a JavaScript function that works for anything. Make it generic, so the types follow the values.

function last(items) {  return items[items.length - 1];}console.log(last([1, 2, 3])); // 3console.log(last(["a", "b"])); // "b"console.log(last([])); // undefined

function last<T>(items: T[]): T | undefined {  return items[items.length - 1];}last([1, 2, 3]); // 3last(["a", "b"]); // "b"last([]); // undefined

function swap(entry) {  return [entry[1], entry[0]];}console.log(swap(["Asha", 21])); // [ 21, 'Asha' ]

function swap<A, B>(entry: [A, B]): [B, A] {  return [entry[1], entry[0]];}swap(["Asha", 21]); // [21, "Asha"]

function mapBox(box, change) {  return { value: change(box.value) };}console.log(mapBox({ value: 21 }, (n) => n + 1)); // { value: 22 }console.log(mapBox({ value: "chai" }, (s) => s.length)); // { value: 4 }

type Box<T> = { value: T };function mapBox<T, U>(box: Box<T>, change: (value: T) => U): Box<U> {  return { value: change(box.value) };}mapBox({ value: 21 }, (n) => n + 1); // { value: 22 }mapBox({ value: "chai" }, (s) => s.length); // { value: 4 }

Generics questions are often the hardest in the round. These short answers cover most of them.

• "What is a generic?" A function, type or class with a type parameter, a blank that is filled in when you use it. It lets one definition work for many types and still keep them straight.
• "Why not just use any?" any turns the checker off, and the output type is lost. A generic keeps the link between input and output.
• "What does T extends X mean?" A constraint. T can be any type, as long as it fits X. It lets you use X's properties inside the function.
• "What is keyof?" An operator that gives the names of a type's properties as a union of exact words. K extends keyof T limits a key to real ones.
• "Does TypeScript need <T> at the call?" Usually not. It infers T from the arguments. You write it yourself when nothing gives it enough to go on, like an empty list.
• "What are examples of built-in generics?" Array<T>, Map<K, V>, Set<T> and Promise<T>.
• "What is a default type parameter?" A fallback used when the blank is left empty, as in type Result<T = string>.
• "When should you not use a generic?" When the blank links nothing, or when you only ever use one type.
• Say it simply. "A generic is a function or type with a blank, so what goes in decides what comes out" is a good answer.

Made by VeraStack Labs