Mapped types, modifiers, and key remapping

Mapped types, including readonly and optionality modifiers, homomorphic mapping over keyof, and key remapping with as.

主题页正文目前为英文。

A mapped type builds a new object type by iterating over a set of keys. The general form is a type with a property [K in Keys]: Value. Partial, Required, Readonly, and Record in the standard typings are ready-made mapped types; those aliases stay on their own pages. This page covers the general syntax, modifiers, and key remapping.

Key remapping with as arrived in TypeScript 4.1. A mapping over keyof T is homomorphic: it tends to copy readonly and optionality from T. A mapping over an explicit key union does not. The examples were checked with TypeScript 5.9.3 under tsc --strict.

Examples were checked with TypeScript 5.9.3 using tsc --strict. See the TypeScript handbook for the complete utility-type catalog.

TypeScript reference overview →

API index

APISummary
Mapped types and modifiersBuild an object type by iterating keys, and add or remove readonly and optionality. Mapping over keyof T preserves those modifiers; mapping over a plain key union does not.
Key remapping with asRename keys with as, or drop them by remapping to never. The as clause is a TypeScript 4.1 feature.
exactOptionalPropertyTypesWith exactOptionalPropertyTypes, an optional property does not accept an explicit undefined unless undefined is part of its value type.

Modifiers and homomorphic mapping

You can add or remove modifiers with readonly, -readonly, ?, and -?. The forms +readonly and +? are the explicit versions of readonly and ?. When the key set is keyof Source, optional and readonly fields stay optional and readonly, so a can be omitted and cannot be assigned. When the key set is written as the union "a" | "b", a becomes a required, writable property. Mutable below uses -readonly to drop the readonly modifier.

Mapped types and modifiers

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

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

Build an object type by iterating keys, and add or remove readonly and optionality. Mapping over keyof T preserves those modifiers; mapping over a plain key union does not.

Type parameterDescription
T / KeysThe source type, or a key union to iterate. Use keyof T when you want a homomorphic mapping that copies modifiers from T.

Produces: A new object type. Mapped types exist only at compile time.

Type errors

  • type error — Omitting a required mapped property is a type error. Assigning to a property that stayed readonly after a homomorphic mapping is a type error.
  • Partial, Required, and Readonly are the standard-library versions of adding ?, removing ?, and adding readonly. See that page for those aliases; this page does not repeat those examples.
typescript
type Flags<T> = { [K in keyof T]: boolean };
type Options = Flags<{ dark: string; preview: string }>;
const flags: Options = { dark: true, preview: false };
// @ts-expect-error missing preview
const incomplete: Options = { dark: true };

type Source = { readonly a?: string; b: number };
type Homo = { [K in keyof Source]: Source[K] };
type Explicit = { [K in "a" | "b"]: Source[K] };

const homo: Homo = { b: 1 };
// @ts-expect-error a stays readonly in a homomorphic mapping over keyof Source
homo.a = "x";

// @ts-expect-error a is required after mapping over the explicit key union
const missing: Explicit = { b: 1 };
const explicit: Explicit = { a: "x", b: 1 };
explicit.a = "y";

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
const mutable: Mutable<Source> = { b: 1 };
mutable.a = "z";
console.log(flags.dark, explicit.a, mutable.a);

Expected output

true y z

Related: Partial, Required, and Readonly, Record

Official documentation →

Key remapping and exact optional properties

The as clause rewrites each key. A template literal type can rename name to getName. A conditional type that produces never drops the key, which is a way to keep only some properties. Key remapping was added in TypeScript 4.1.

The project tsconfig and the default examples on these pages use tsc --strict without exactOptionalPropertyTypes. Under that default, { a?: string } accepts { a: undefined }. The last example enables --exactOptionalPropertyTypes with a tsc-flags comment so the checker runs that extra flag; then { a: undefined } is a type error unless undefined is part of the value type. This is a compiler option effect, not a change to the mapped-type syntax.

Key remapping with as

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

type OnlyStrings<T> = {
    [K in keyof T as T[K] extends string ? K : never]: T[K];
};

Rename keys with as, or drop them by remapping to never. The as clause is a TypeScript 4.1 feature.

Type parameterDescription
KEach key in the iteration. string & K is used when the key might be string | number | symbol and a template needs a string.

Produces: A new object type whose keys are the remapped names that did not become never.

Type errors

  • type error — The original key is not present after remapping, so reading name on a Getters type is a type error. A dropped key such as id on OnlyStrings is also a type error.
  • Template literal types used in remapping are documented on the template literals page.
typescript
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};
type Person = { name: string; age: number };
const getters: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};
console.log(getters.getName(), getters.getAge());
// @ts-expect-error the remapped key is getName, not name
getters.name;

type OnlyStrings<T> = {
  [K in keyof T as T[K] extends string ? K : never]: T[K];
};
const picked: OnlyStrings<{ id: number; label: string }> = { label: "ok" };
// @ts-expect-error id is not a string field, so the key was dropped
picked.id;

Expected output

Ada 36

Related: Template literal types

Official documentation →

exactOptionalPropertyTypes

type T = { a?: string };

With exactOptionalPropertyTypes, an optional property does not accept an explicit undefined unless undefined is part of its value type.

Type parameterDescription
compiler optionexactOptionalPropertyTypes is not part of --strict and is not enabled in this project tsconfig. The example requests it with a tsc-flags comment.

Produces: The type is still an object type with an optional property. The flag changes assignability, not the syntax of ?.

Type errors

  • type error — Under exactOptionalPropertyTypes, { a: undefined } is not assignable to { a?: string }. The measured error in TypeScript 5.9.3 is TS2375.
  • The Partial page also notes that its examples use default --strict without this flag. The checker only runs extra flags from an allowlisted tsc-flags comment.
typescript
// tsc-flags: --exactOptionalPropertyTypes
type T = { a?: string };
const empty: T = {};
const present: T = { a: "x" };
// @ts-expect-error undefined is not assignable to string when exactOptionalPropertyTypes is on
const explicitUndefined: T = { a: undefined };
console.log("exact optional");

Expected output

exact optional

Related: Partial, Required, and Readonly

Official documentation →