Mapped types: iterate a type's keys to build a new one

Iterating keys with K in keyof T

Ask yourself: how does Partial<Config> know to make every field optional without listing them? Because mapped types don’t know the keys ahead of time — they compute them at instantiation. That’s the power, and it’s why adding a field to Config automatically makes it optional in Partial<Config> with no extra work.

A mapped type looks like an index signature, but in makes it a loop: for each key K in the union keyof T, emit a property. Inside, T[K] is the original value type at that key.

type Stringify<T> = { [K in keyof T]: string };

type Config = { port: number; host: string; tls: boolean };
type S = Stringify<Config>;
// ^? { port: string; host: string; tls: string }

keyof Config is "port" | "host" | "tls"; the mapped type iterates that union and sets every value to string. To keep the original value type, reference T[K]:

type Clone<T> = { [K in keyof T]: T[K] };
type C = Clone<Config>;
// ^? { port: number; host: string; tls: boolean }

Modifiers: add or strip ? and readonly

A mapped type can attach or remove the two property modifiers. ? makes optional, -? removes optionality; readonly adds it, -readonly removes it. This is how the standard utilities are built — here they are from scratch:

type MyPartial<T>  = { [K in keyof T]?: T[K] };           // add ?
type MyRequired<T> = { [K in keyof T]-?: T[K] };          // strip ?
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };   // add readonly
type MyMutable<T>  = { -readonly [K in keyof T]: T[K] };  // strip readonly

type Src = { a?: number; readonly b: string };

type P = MyPartial<Src>;  // ^? { a?: number; readonly b?: string }
type R = MyRequired<Src>; // ^? { a: number; readonly b: string }
type M = MyMutable<Src>;  // ^? { a?: number; b: string }

Note MyRequired<Src> turns a? into a required a: number (the ? is stripped) but leaves readonly b readonly — -? touches only optionality. MyMutable strips the readonly from b but leaves a optional. The modifiers are orthogonal.

Homomorphic vs non-homomorphic — the subtle, crucial difference

When a mapped type is written { [K in keyof T]: ... } — iterating directly over keyof T of a single type parameter — it is homomorphic. Homomorphic mapped types do two quiet but important things: they preserve the original modifiers (so Clone above kept readonly b), and they preserve array- and tuple-ness:

type Clone<T> = { [K in keyof T]: T[K] }; // homomorphic

type CA = Clone<number[]>;       // ^? number[]        — still an array
type CT = Clone<[1, 2]>;         // ^? [1, 2]          — still a tuple
type CR = Clone<readonly string[]>; // ^? readonly string[]  — readonly kept

Now compare a mapped type that iterates over a key union it received as a separate parameter — non-homomorphic:

type FromKeys<K extends PropertyKey, V> = { [P in K]: V };

type Obj = FromKeys<"a" | "b", number>;
// ^? { a: number; b: number }     — fine for object keys
type Broken = FromKeys<keyof number[], unknown>;
// ^? a plain object with number[]'s string keys ("length", "push", ...) — NOT an array

FromKeys maps over a bare key union K, not over keyof T, so TypeScript has no original container to preserve — the result is always a plain object. This is exactly why Record<K, V> = { [P in K]: V } produces objects, while Partial/Readonly (written over keyof T) faithfully preserve arrays and tuples.

The cost side: mapped types scale with your object’s width

A mapped type instantiates one property per key, so its cost is linear in the key count — usually negligible. The blow-up comes from composition: Partial<DeepReadonly<Pick<T, ...>>> over a 200-field generated type re-materialises a full object at each layer, and stacked over a union of such types the property count multiplies. The hard ceiling is the same union/object limits as everywhere else — a mapped type whose value expression distributes a conditional over a large union can hit the 100,000-member Expression produces a union type that is too complex to represent wall.

The senior breakpoint: a mapped type earns its keep when the transform must apply uniformly across an unknown or evolving set of keys — Partial<Config> stays correct when someone adds a field. It is over-engineering when the object is small and fixed: hand-writing the optional twin is two extra lines a reader understands instantly, where the mapped type forces them to mentally expand it. And the modifier/homomorphism rules are a real maintenance tax — the next engineer must know that routing keys through as or a separate parameter silently drops readonly and collapses arrays (the bugs in this lesson). When the shape is generated from a schema anyway (Prisma, GraphQL, OpenAPI), prefer the codegen output’s flat interface over wrapping it in three layers of mapped utilities; the generated interface is hoverable and diff-able, the deep mapped tower is neither.