TypeScript Mapped Types: The Feature That Changes How You Design Types

You've written this before:

interface User {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

interface UserFormState {
  id: boolean;
  name: boolean;
  email: boolean;
  role: boolean;
}

A UserFormState where every field is a boolean — did it change? Was it touched? You maintain two types that mirror each other. Add a field to User, forget to update UserFormState, and your types lie to you.

Mapped types solve this. They let you derive one type from another automatically. When User changes, UserFormState updates itself.

Let's start with the basics and work up to the patterns that will change how you architect TypeScript code.

The Syntax: What a Mapped Type Actually Is

A mapped type iterates over the keys of another type and transforms each property. Here's the simplest form:

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

This reads: "for each key K in the set of keys of T, create a property with that key, and give it the same type as T[K]." It's a no-op — it produces an identical type. The power comes from what you do inside the braces.

Let's solve the form state problem:

type FormState<T> = {
  [K in keyof T]: boolean;
};

// Derive from User automatically
type UserFormState = FormState<User>;
//   ^? { id: boolean; name: boolean; email: boolean; role: boolean; }

// Add a field to User — UserFormState updates automatically

One type parameter, one mapped type, zero duplication. Add age: number to User, and UserFormState gets age: boolean without touching a single line.

Modifiers: Making Properties Optional, Readonly, or Mutable

Mapped types can add or remove type modifiers. The two modifiers are readonly and ? (optional).

// Make everything readonly
type Readonly<T> = {
  readonly [K in keyof T]: T[K];
};

// Make everything optional
type Partial<T> = {
  [K in keyof T]?: T[K];
};

// Remove readonly (make everything writable)
type Mutable<T> = {
  -readonly [K in keyof T]: T[K];
};

// Remove optional (make everything required)
type Required<T> = {
  [K in keyof T]-?: T[K];
};

These aren't theoretical. Readonly<T>, Partial<T>, and Required<T> are built into TypeScript's standard library. But understanding the syntax lets you create your own.

A real example: you have a configuration object that should be frozen after creation, but you want to build it with mutations internally.

interface AppConfig {
  readonly databaseUrl: string;
  readonly apiKey: string;
  readonly port: number;
}

type Writable<T> = {
  -readonly [K in keyof T]: T[K];
};

function createConfig(): AppConfig {
  // Build with mutations, then cast
  const config: Writable<AppConfig> = {
    databaseUrl: '',
    apiKey: '',
    port: 0,
  };

  config.databaseUrl = process.env.DATABASE_URL!;
  config.apiKey = process.env.API_KEY!;
  config.port = parseInt(process.env.PORT ?? '3000', 10);

  return config as AppConfig;
}

The -readonly modifier strips readonly during construction, then the return type AppConfig freezes it for consumers. Clean, type-safe, and minimal code.

Key Remapping with `as` (TypeScript 4.1+)

Here's where mapped types get genuinely powerful. You can transform the keys themselves using the as clause:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

interface Person {
  name: string;
  age: number;
}

// Result:
type PersonGetters = Getters<Person>;
//   ^? { getName: () => string; getAge: () => number; }

This isn't just clever syntax. It's how you create type-safe wrappers, API clients, and state managers without manually listing every property.

Filtering Keys

You can also exclude keys by resolving them to never in the as clause:

// Exclude methods, keep only data properties
type DataProperties<T> = {
  [K in keyof T as T[K] extends Function ? never : K]: T[K];
};

type StripMethods<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
};

class UserService {
  name: string = '';
  age: number = 0;
  save(): Promise<void> { return Promise.resolve(); }
  delete(): Promise<void> { return Promise.resolve(); }
}

type UserData = StripMethods<UserService>;
//   ^? { name: string; age: number; }
//   save() and delete() are gone

This pattern is invaluable when you're building serialization layers. Your API response types shouldn't include methods, but you also shouldn't maintain a parallel type by hand.

Real Example: Type-Safe API Client

Let's put key remapping to work. Say you have a set of API endpoints:

interface Endpoints {
  users: { list: { method: 'GET'; path: '/users'; }; create: { method: 'POST'; path: '/users'; }; };
  products: { list: { method: 'GET'; path: '/products'; }; update: { method: 'PUT'; path: '/products/:id'; }; };
}

// Convert endpoints into a flat set of callable methods
type ApiClient<T> = {
  [K1 in keyof T]: {
    [K2 in keyof T[K1] as `${string & K2}${Capitalize<string & K1>}`]: 
      (params?: any) => Promise<any>;
  };
};

// Usage:
type Client = ApiClient<Endpoints>;
// Result:
// {
//   users: { listUsers: (params?: any) => Promise<any>; createUsers: (params?: any) => Promise<any>; };
//   products: { listProducts: (params?: any) => Promise<any>; updateProducts: (params?: any) => Promise<any>; };
// }

The key remapping works like this:

Outer loop (K1): iterates over the top-level keys (users, products)
Inner loop (K2): iterates over the second-level keys (list, create)
as clause transforms the key name: list + users → listUsers, create + users → createUsers
Each resolved method returns Promise<any>

The result is a nested client where routes are grouped by resource: client.users.listUsers(). The as clause did the heavy lifting of naming each method without you typing out all the combinations.

Combining Mapped Types with Template Literal Types

Template literal types and mapped types work together to solve real problems.

CSS Property Prefixes

type CSSValue = string | number;

type CSSProperties = {
  margin: CSSValue;
  padding: CSSValue;
  border: CSSValue;
};

type Responsive<T> = {
  [K in keyof T as `${string & K}Mobile`]: T[K];
} & {
  [K in keyof T as `${string & K}Desktop`]: T[K];
};

type ResponsiveCSS = Responsive<CSSProperties>;
//   ^? { marginMobile: CSSValue; marginDesktop: CSSValue;
//        paddingMobile: CSSValue; paddingDesktop: CSSValue;
//        borderMobile: CSSValue; borderDesktop: CSSValue; }

State Machine Event Handlers

type States = 'idle' | 'loading' | 'success' | 'error';

type EventHandlers = {
  [K in States as `onEnter${Capitalize<K>}`]: () => void;
} & {
  [K in States as `onLeave${Capitalize<K>}`]: () => void;
};

// Result:
// { onEnterIdle: () => void; onEnterLoading: () => void;
//   onEnterSuccess: () => void; onEnterError: () => void;
//   onLeaveIdle: () => void; ... }

No more manually typing eight handler signatures that mirror your four states. Add a state — get two new handlers automatically. The compiler enforces completeness.

Conditional Types + Mapped Types = Unstoppable

Conditional types (T extends U ? X : Y) let you transform property values based on the type of each key. Combined with mapped types, this is how you build the most expressive type utilities.

// Convert all Date properties to ISO strings
type DatesToStrings<T> = {
  [K in keyof T]: T[K] extends Date ? string : T[K];
};

interface Event {
  id: number;
  name: string;
  createdAt: Date;
  updatedAt: Date;
  scheduledFor: Date;
}

type SerializedEvent = DatesToStrings<Event>;
//   ^? { id: number; name: string;
//        createdAt: string; updatedAt: string; scheduledFor: string; }

This is the core of serialization. When you send an object over the wire, Date objects become strings. This type enforces that transformation at compile time.

Deep Wrapping: API Response Wrapper

You can wrap an entire type hierarchy using conditional types inside mapped types:

// Wrap every property value in a Result-like container
type DeepResult<T> = {
  [K in keyof T]: T[K] extends object
    ? DeepResult<T[K]> & { success: boolean; error: string | null }
    : { value: T[K]; success: boolean; error: string | null };
};

interface Config {
  database: { host: string; port: number };
  features: { darkMode: boolean; beta: boolean };
}

type ConfigResult = DeepResult<Config>;
// database: DeepResult<{ host: string; port: number }> & { success: boolean; error: string | null }
//   → host: { value: string; success: boolean; error: string | null }
//   → port: { value: number; success: boolean; error: string | null }
// features: same, plus { success: boolean; error: string | null } at each level

Real Example: API Response Transformer

type ApiResponse<T> = {
  data: T;
  error: null | { message: string; code: number };
  meta: {
    page: number;
    totalPages: number;
  };
};

// Flatten into a cleaner client-side type — strip null unions, simplify errors
type FlattenedResponse<T> = {
  [K in keyof T as T[K] extends null | undefined ? never : K]: T[K];
} & {
  error: string | null; // Replace full error object with just a message
};

type ClientResponse = FlattenedResponse<ApiResponse<{ id: number }>>;

Pattern: Type-Safe Event Emitter

Let's build something real. A generic event emitter where each event name maps to its payload type, and on/emit are fully typed.

type EventMap = {
  userLoggedIn: { userId: string; timestamp: number };
  userLoggedOut: { userId: string };
  error: { message: string; code: number; fatal: boolean };
  dataLoaded: { resource: string; items: number };
};

class TypedEmitter<T extends Record<string, unknown>> {
  private handlers = new Map<keyof T, Set<Function>>();

  on<K extends keyof T>(event: K, handler: (payload: T[K]) => void): void {
    if (!this.handlers.has(event)) {
      this.handlers.set(event, new Set());
    }
    this.handlers.get(event)!.add(handler);
  }

  emit<K extends keyof T>(event: K, payload: T[K]): void {
    this.handlers.get(event)?.forEach(handler => handler(payload));
  }

  off<K extends keyof T>(event: K, handler: (payload: T[K]) => void): void {
    this.handlers.get(event)?.delete(handler);
  }
}

// Usage — fully type-checked
const bus = new TypedEmitter<EventMap>();

bus.on('userLoggedIn', (payload) => {
  // payload is { userId: string; timestamp: number }
  console.log(payload.userId); // ✅ typed
  console.log(payload.timestamp); // ✅ typed
  console.log(payload.fatal); // ❌ error: Property 'fatal' does not exist
});

bus.emit('error', { message: 'Disk full', code: 500, fatal: true }); // ✅
bus.emit('userLoggedIn', { userId: 'abc' }); // ❌ missing timestamp

This works because of two mapped type behaviors:

T extends Record<string, unknown> constrains the map shape
K extends keyof T picks a specific event, and T[K] resolves its payload

No any, no type assertions, no runtime overhead beyond a Map.

Pattern: Form State with Dirty Tracking

Earlier we turned every field to boolean. Let's build something more useful — a dirty-tracking form state that knows both the original type and what changed.

type DirtyState<T> = {
  [K in keyof T]: {
    value: T[K];
    dirty: boolean;
    original: T[K];
  };
};

interface Profile {
  displayName: string;
  bio: string;
  age: number;
  email: string;
}

type ProfileForm = DirtyState<Profile>;
// Each field becomes: { value: string; dirty: boolean; original: string; }

The mapped type eliminates an entire category of bugs. Add a new field to Profile and every form component that uses ProfileForm gets the new field automatically.

When NOT to Use Mapped Types

Mapped types add complexity. They're not always the right tool.

Skip mapped types when:

You have two or three fields. Just write the type. type Status = 'idle' | 'loading' | 'done' is clearer than any derived type.
The mapping is one-to-one with no transformation. type Copy<T> = { [K in keyof T]: T[K] } is useless — just use the original type.
You need runtime behavior. Mapped types only operate at the type level. If you need to actually iterate keys at runtime, you still need Object.keys() or a for...in loop.
Readability suffers. If a mapped type takes more than 30 seconds to understand, extract it behind a well-named utility or add a comment.

Use mapped types when:

You're deriving one type from another (form state, serialized version, API client)
You're transforming keys systematically (prefix, suffix, filter)
You're adding/removing modifiers across the board (readonly, optional)
You have a union of string literals and need an object type keyed by them

Where to Go Next

Mapped types are one layer in TypeScript's type system. If this clicked, dive into:

Conditional types with infer — extracting types from inside other types
Template literal types for string manipulation at the type level
Variadic tuple types for type-safe function arguments

The TypeScript handbook is excellent, but the best way to learn is to open your editor and try mapping over your own interfaces. Change a key, add a modifier, see what breaks. That's how the type system stops being a compiler and starts being a tool you design with.

Kai Thorne writes about TypeScript, Python, and building better software. Follow for practical, no-fluff technical content.