Writing your own utility types

The built-in helpers are types you can write

Partial, Pick, Readonly, and the other helpers from the Partial, Pick, Omit & friends lesson aren't magic. Each one is a short type alias, a name for a type, written in a file that comes with TypeScript. They are built from the same parts you already know: mapped types and conditional types. So you can write them yourself:

1type MyPartial<T> = {2  [Key in keyof T]?: T[Key];3};4 5type Profile = { name: string; email: string; age: number };6type ProfileChange = MyPartial<Profile>;7//   ^?8const change: ProfileChange = { email: "asha@example.com" };9console.log(change);

Lines 1 to 3 make MyPartial. T is a type parameter: a name for whatever type you pass in the angle brackets. Line 2 is a mapped type: for each Key in keyof T, make a property with that name, add ? so it may be left out, and give it the type T[Key], the same type it had in T.

Line 5 describes a profile. Line 6 uses the helper, and the query on line 7 shows every property with a ?. TypeScript also writes | undefined after each type, because a property that is left out reads as undefined. Line 8 gives only an email, and line 9 prints { email: 'asha@example.com' }.

Rebuild Partial, Readonly, and Pick

Most object helpers are the same mapped type with one small change. Press the buttons to swap the helper's body on line 3, and watch what it does to the profile:

1type Profile = { name: string; email: string; age?: number };2 3type Helper<T> = { [Key in keyof T]?: T[Key] };4 5type Draft = Helper<Profile>;6//   ^?7const draft: Draft = { name: "Asha", email: "asha@example.com" };8draft.name = "Ravi";9console.log(draft.name);

Line 1 is a profile whose age may be missing. Line 5 applies the helper, and the query on line 6 shows the result. Line 7 makes a draft with a name and an email, and line 8 changes the name. Each recipe changes one thing:

• ? after the brackets adds a question mark to every key: Partial.
• -? takes them away: Required. Now line 7 is missing age.
• readonly in front locks every key: Readonly. Now line 8 can't change the name.
• T[Key] | null changes the value part instead, which makes a helper TypeScript doesn't have.

Notice that age keeps its ? in the Readonly, Nullable, and Plain copy recipes. A mapped type over keyof T copies each property's ? and readonly unless you add or remove them.

Pick walks only some keys. It takes a second type parameter, K, for the keys to keep, and K extends keyof T says they must be real keys of T (the keyof & typeof lesson covers keyof). A wrong key is an error, on purpose here:

1type MyPick<T, K extends keyof T> = { [Key in K]: T[Key] };2 3type Profile = { name: string; email: string; age: number };4type Contact = MyPick<Profile, "name" | "email">;5//   ^?6type Phone = MyPick<Profile, "phone">;

Line 1 walks Key in K instead of every key, and keeps each type with T[Key]. Line 4 keeps the name and the email, and the query on line 5 shows just those two. Line 6 asks for a phone. TypeScript says Type '"phone"' does not satisfy the constraint 'keyof Profile': phone isn't one of the profile's keys, so it can't be picked.

Omit is built from other helpers: pick every key except the ones you name. Exclude, from the ReturnType, Awaited & more lesson, takes them out of the union of keys. Writing it yourself lets you make it stricter than the built-in one, on purpose here:

1type MyOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;2 3type User = { id: number; name: string; email: string };4type PublicUser = MyOmit<User, "email">;5//   ^?6type Typo = MyOmit<User, "emial">;7type BuiltInTypo = Omit<User, "emial">;

Line 1 picks the keys of T that are left after excluding K. Line 4 leaves out the email, and the query on line 5 shows the id and name. Line 6 has a typo, "emial", and gets the same error as MyPick, because MyOmit says K extends keyof T. Line 7 makes the same typo with the built-in Omit, and there is no error: its K only has to be some key name, not one of User's.

The table below shows how TypeScript's library writes each helper. Read each row as: the helper, its recipe, and what it does.

Helpers TypeScript doesn't have

Once you can read the recipes, you can write helpers for your own app. A common one: a new user has no id or createdAt yet, because the server adds them. So those two keys should be optional, and the rest required:

1type User = { id: number; name: string; email: string; createdAt: string };2 3type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;4 5type NewUser = Optional<User, "id" | "createdAt">;6//   ^?7const asha: NewUser = { name: "Asha", email: "asha@example.com" };8console.log(asha.name);

Line 3 makes Optional from built-in helpers. Omit<T, K> is everything except those keys, required as before. Partial<Pick<T, K>> is just those keys, made optional. The & joins the two into one type with all the properties (the Intersection types lesson covers &). Line 7 makes a user without an id, and line 8 prints Asha.

It works, but look at the query on line 6. TypeScript shows the recipe, not the result. A later section fixes that. First, one more kind of helper: one that uses itself.

Types that refer to themselves

Some data has the same shape at every level: a menu whose items have their own items, or comments with replies. A type for it can mention itself. That's called a recursive type, like a recursive function, which calls itself (the Recursion lesson covers those):

1type MenuItem = { label: string; children: MenuItem[] };2 3const menu: MenuItem = {4  label: "Shop",5  children: [6    { label: "Tea", children: [] },7    { label: "Cakes", children: [{ label: "Birthday", children: [] }] },8  ],9};10console.log(menu.children[1].children[0].label);

Line 1 says a MenuItem has a label and a list of children, and each child is a MenuItem too. Lines 3 to 9 are a shop menu three levels deep, and the one type fits every level. A child with no children of its own has an empty list. Line 10 reads the second child's first child and prints Birthday.

A recursive type can also be a union. Here is a type for any value JSON.stringify can save and load again (the Typing fetch & JSON lesson works with JSON). Line 4 is an error on purpose:

1type Json = string | number | boolean | null | Json[] | { [key: string]: Json };2 3const reply: Json = { user: "Asha", tags: ["tea", 3], seen: true };4const withDate: Json = { when: new Date() };

Line 1 says a JSON value is text, a number, true or false, null, a list of JSON values, or an object whose values are JSON values. Line 3 nests a list inside an object, and it fits. Line 4 puts a Date inside, and TypeScript says Type '{ when: Date; }' is not assignable to type 'Json': a date isn't one of the kinds of value JSON can hold.

The self-reference has to sit inside something, like an object property or a list, so TypeScript can look at one level at a time. A type that is directly itself is an error, on purpose here:

1type Price = Price | number;

To work out Price, TypeScript would first need to know Price. It says Type alias 'Price' circularly references itself. You met the other kind of recursive type, a conditional type that calls itself, as UnwrapAll in the infer keyword lesson.

DeepPartial and DeepReadonly

Partial and Readonly only change the top level of an object. A settings object with groups inside needs a helper that goes into every level. Combine a mapped type, a conditional type, and recursion:

1type DeepPartial<T> = {2  [Key in keyof T]?: T[Key] extends object ? DeepPartial<T[Key]> : T[Key];3};4 5type Settings = {6  theme: { mode: "light" | "dark"; accent: string };7  alerts: { email: boolean; push: boolean };8};9 10type ThemeChange = DeepPartial<Settings["theme"]>;11//   ^?

Line 2 does the work. For each key, it makes the property optional, then asks a question about its type: T[Key] extends object, "is this property an object?" If yes, the answer is DeepPartial<T[Key]>: the same helper again, one level down. If no, like a string or a boolean, the type stays as it is, and the recursion stops there.

Lines 5 to 8 describe settings with two groups. Line 10 applies the helper to the theme group, and the query on line 11 shows that the group's own properties are optional now. Press the buttons to compare it with Partial on a whole change:

1type DeepPartial<T> = {2  [Key in keyof T]?: T[Key] extends object ? DeepPartial<T[Key]> : T[Key];3};4 5type Settings = {6  theme: { mode: "light" | "dark"; accent: string };7  alerts: { email: boolean; push: boolean };8};9 10const change: Partial<Settings> = { theme: { mode: "dark" } };11console.log(JSON.stringify(change));

With Partial, line 10 gets an error, because a theme you give must still have every property. With DeepPartial, you can give just the part that changed. What you do give is still checked: "blue" isn't a mode.

DeepReadonly is the same shape with readonly instead of ?. Line 8 and line 9 are errors on purpose:

1type DeepReadonly<T> = {2  readonly [Key in keyof T]: T[Key] extends object ? DeepReadonly<T[Key]> : T[Key];3};4 5type Settings = { theme: { mode: "light" | "dark" }; tags: string[] };6 7const settings: DeepReadonly<Settings> = { theme: { mode: "light" }, tags: ["new"] };8settings.theme.mode = "dark";9settings.tags.push("sale");10console.log(settings.theme.mode, settings.tags);

With the built-in Readonly, line 8 would be allowed: it only locks the top level (the Mapped types lesson shows this). With DeepReadonly, TypeScript says Cannot assign to 'mode' because it is a read-only property. It even goes into the list: a mapped type over an array type makes a read-only array, so line 9 gets Property 'push' does not exist on type 'readonly string[]'. Like every type, it doesn't freeze anything while the page runs: line 10 still prints dark [ 'new', 'sale' ].

Keeping types readable

A helper is only useful if people can read what it makes. The Optional helper showed its recipe in the hover, not its result. The plain copy recipe from the playground fixes that:

1type User = { id: number; name: string; email: string; createdAt: string };2 3type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;4type Prettify<T> = { [Key in keyof T]: T[Key] };5 6type NewUser = Optional<User, "id" | "createdAt">;7//   ^?8type NewUserFlat = Prettify<NewUser>;9//   ^?

Line 4 makes Prettify, a mapped type that copies every key with its type and modifiers. It changes nothing about which values fit. But to show a mapped type, TypeScript has to list its keys, so the query on line 9 shows one flat object: the name and the email required, the id and createdAt optional. The query on line 7, without it, shows the recipe. You can also put it inside the helper, so every use is flat: Prettify<Omit<T, K> & Partial<Pick<T, K>>>.

A few habits keep your own helpers easy to read and to trust:

• Reach for a built-in helper first. Write your own only when none fits.
• Give each helper a plain name that says what it makes, like Optional or DeepPartial, and type parameter names that say what they hold, like Key.
• Build big helpers from small ones, as Optional uses Omit, Pick, and Partial.
• Check each helper with a // ^? line on a real type, and try one value that should fail.
• Only go deep when your data is deep. A recursive helper makes every hover and error message longer.

Saving part of a nested settings object

A settings page saves only what the reader changed: maybe the theme's mode and one alert. DeepPartial types that change, and the function fills in the rest from the saved settings:

1type DeepPartial<T> = {2  [Key in keyof T]?: T[Key] extends object ? DeepPartial<T[Key]> : T[Key];3};4 5type Settings = {6  theme: { mode: "light" | "dark"; accent: string };7  alerts: { email: boolean; push: boolean };8};9 10function updateSettings(current: Settings, change: DeepPartial<Settings>): Settings {11  return {12    theme: { ...current.theme, ...change.theme },13    alerts: { ...current.alerts, ...change.alerts },14  };15}16 17const saved: Settings = {18  theme: { mode: "light", accent: "orange" },19  alerts: { email: true, push: true },20};21const updated = updateSettings(saved, { theme: { mode: "dark" }, alerts: { push: false } });22console.log(updated.theme.mode, updated.theme.accent, updated.alerts.push);

Lines 1 to 8 are the helper and the settings from before. Line 10 says updateSettings takes the current settings and a change of type DeepPartial<Settings>, and gives back whole Settings. Lines 12 and 13 copy each group and then lay the changed parts over it with the spread syntax ... (the Spread and rest lesson covers it). Lines 17 to 20 are the saved settings. Line 21 changes only the mode and push alerts, and line 22 prints dark orange false: the accent was kept.

Common mix-ups

T[Key] extends object is true for more than plain objects. Arrays are objects, and so are functions. For arrays that works out, as you saw. For a function, it doesn't, and line 15 is an error on purpose:

1type DeepReadonly<T> = {2  readonly [Key in keyof T]: T[Key] extends object ? DeepReadonly<T[Key]> : T[Key];3};4 5type Cart = {6  items: { name: string; price: number }[];7  checkout: (total: number) => string;8};9 10function lock(cart: Cart): DeepReadonly<Cart> {11  return cart;12}13 14const cart = lock({ items: [{ name: "Tea", price: 3 }], checkout: (total) => `Paid ${total}` });15console.log(cart.checkout(3));

Line 7 gives the cart a checkout function. DeepReadonly sees an object and turns it into a mapped type, and a mapped type can't be called. Line 15 gets This expression is not callable. The code still runs and prints Paid 3: only the type is wrong. The fix is to check for a function first and leave it as it is:

1type DeepReadonly<T> = {2  readonly [Key in keyof T]: T[Key] extends (...args: never[]) => unknown3    ? T[Key]4    : T[Key] extends object5      ? DeepReadonly<T[Key]>6      : T[Key];7};8 9type Cart = {10  items: { name: string; price: number }[];11  checkout: (total: number) => string;12};13 14function lock(cart: Cart): DeepReadonly<Cart> {15  return cart;16}17 18const cart = lock({ items: [{ name: "Tea", price: 3 }], checkout: (total) => `Paid ${total}` });19console.log(cart.checkout(3));

Line 2 asks first whether the property is a function: (...args: never[]) => unknown is a type every function fits. If it is, line 3 keeps it. Only otherwise do lines 4 to 6 go deeper. Now line 19 type checks and prints Paid 3.

• "Utility types are built into the compiler." No. Partial, Pick, Omit, and friends are type aliases in a library file. You can read them and write your own. Only a few, like the Uppercase from Template literal types, are built into the compiler.
• "A mapped type always drops ? and readonly." No. Walking keyof T keeps each property's modifiers unless you write -? or -readonly.
• "Pick<T, K> works without K extends keyof T." No. Without it, K could be anything, and T[Key] might not exist.
• "Partial makes nested objects optional too." No. It changes only the top level. Use a recursive DeepPartial.
• "A type can refer to itself any way it likes." No. The self-reference must sit inside an object, a list, or a conditional type, not be the whole type.
• "A deep helper is safe on any object." No. Functions are objects too. Check for them first.
• "Prettify changes the type." No. It changes only how the type is shown.

The table below sets the built-in helpers beside the deep ones. Read each row as: the helper, how far it goes, and what that means.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code: the errors and ^? answers update as you type. Try a guess first, then use the hints.

1type Nullable<T> = { [Key in keyof T]: T[Key] | null };2 3type Todo = { title: string; done: boolean };4type TodoDraft = Nullable<Todo>;

1type Nullable<T> = { [Key in keyof T]: T[Key] | null };2 3type Todo = { title: string; done: boolean };4type TodoDraft = Nullable<Todo>;5//   ^?

type MyPick<T, K extends keyof T> = { [Key in K]: T[Key] };

type Todo = { title: string; done: boolean };
type Summary = MyPick<Todo, "title">;
type Planned = MyPick<Todo, "title" | "due">;

1type MyPick<T, K extends keyof T> = { [Key in K]: T[Key] };2 3type Todo = { title: string; done: boolean };4type Summary = MyPick<Todo, "title">;5type Planned = MyPick<Todo, "title" | "done">;

1type MyReadonly<T> = { [Key in keyof T]: T[Key] };2 3type Todo = { title: string; done: boolean };4const todo: MyReadonly<Todo> = { title: "Buy tea", done: false };5todo.done = true;6console.log(todo.done);

1type MyReadonly<T> = { readonly [Key in keyof T]: T[Key] };2 3type Todo = { title: string; done: boolean };4const todo: MyReadonly<Todo> = { title: "Buy tea", done: false };5todo.done = true;6console.log(todo.done);

1type ValueOf<T> = unknown;2 3type Settings = { theme: "light" | "dark"; fontSize: number };4const value: ValueOf<Settings> = true;

1type ValueOf<T> = T[keyof T];2 3type Settings = { theme: "light" | "dark"; fontSize: number };4const value: ValueOf<Settings> = true;

1type DeepReadonly<T> = {2  readonly [Key in keyof T]: T[Key];3};4 5type Order = { id: number; address: { city: string } };6const order: DeepReadonly<Order> = { id: 7, address: { city: "Pune" } };7order.address.city = "Goa";8console.log(order.address.city);

1type DeepReadonly<T> = {2  readonly [Key in keyof T]: T[Key] extends object ? DeepReadonly<T[Key]> : T[Key];3};4 5type Order = { id: number; address: { city: string } };6const order: DeepReadonly<Order> = { id: 7, address: { city: "Pune" } };7order.address.city = "Goa";8console.log(order.address.city);

1type Comment = { text: string; replies: unknown[] };2 3const thread: Comment = { text: "Love this tea", replies: [{ text: "Me too", replies: [] }] };4console.log(thread.replies[0].text);

1type Comment = { text: string; replies: Comment[] };2 3const thread: Comment = { text: "Love this tea", replies: [{ text: "Me too", replies: [] }] };4console.log(thread.replies[0].text);

Check your understanding

For each question, ask: which keys does the helper walk, and what does it do to each property? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Utility types are type aliases with type parameters. Partial is { [P in keyof T]?: T[P] } in TypeScript's library.
• Most object helpers are one mapped type with one change: ?, -?, readonly, or a new value type. Walking keyof T keeps each property's modifiers.
• K extends keyof T keeps a helper's keys real, which makes your own Omit stricter than the built-in one.
• A recursive type refers to itself inside an object, a list, or a conditional type, to describe trees and nested data.
• DeepPartial and DeepReadonly call themselves for each property that is an object. Check for functions first.
• Prettify, a plain copy mapped type, makes a hover show the result instead of the recipe.

Coming next: Modules & type imports. It shares types between files with import and export, so a helper like DeepPartial is written once for the whole app.