How do mapped types work, including key remapping and + / - modifiers?

A mapped type iterates a union of keys and builds one property per member: { [K in "a" | "b"]: number }. The key union is usually keyof T, and T[K] reads the original property type.

Modifiers. When the keys come from keyof T (or from a type parameter constrained to keyof T), the mapped type is homomorphic: it copies each property's readonly and ? from T. You change that with + / - prefixes (PR 21919):

• -readonly removes readonly, +readonly (or plain readonly) adds it.
• -? makes a property required and, under strictNullChecks, also strips undefined that ? had added; ? / +? makes it optional.

This is how Partial, Required and Readonly are defined.

Key remapping (TS 4.1): [K in keyof T as NewKey]: T[K]. NewKey can be any type computed from K, typically a template literal (get${Capitalize<K>}). If it resolves to never for a key, that property is dropped, so as Exclude<K, "kind"> filters without a helper Omit. Because as is a clause on a keyof T mapping, modifiers are still copied. K in the as clause ranges over the original keys, so T[K] stays valid.

Behaviours to know:

• Homomorphic mapped types distribute over unions and leave primitives unchanged; applied to arrays and tuples they map the elements and keep the array or tuple shape.
• You cannot declare extra properties next to the [K in ...] part (TS7061); intersect two types instead.
• Iterating Exclude<keyof T, X> directly (no as) is not homomorphic and loses modifiers.
• With as, the key set can be any union, not only string | number | symbol: you can map over a union of objects with as E["kind"].

// TypeScript 7.0.2 and 5.9.3, --strict
type Point = { readonly x: number; y?: string; z: boolean };

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type Concrete<T> = { [K in keyof T]-?: T[K] };
type A = Mutable<Point>; // { x: number; y?: string | undefined; z: boolean; }
type B = Concrete<Point>; // { readonly x: number; y: string; z: boolean; }

type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
type C = Getters<{ name: string; age: number }>; // { getName: () => string; getAge: () => number; }

type OmitAs<T, K> = { [P in keyof T as Exclude<P, K>]: T[P] };
type D = OmitAs<Point, "z">; // { readonly x: number; y?: string | undefined; }

type Loose<T, K extends keyof T> = { [P in Exclude<keyof T, K>]: T[P] };
type E = Loose<Point, "z">; // { x: number; y: string | undefined; }: modifiers lost

type F = Mutable<readonly string[]>; // string[]

type Bad = { [K in "a"]: K; extra: 1 };
// Error TS7061: A mapped type may not declare properties or methods.

• Writing the key union by hand ([K in Exclude<keyof T, X>]) and silently dropping readonly and ?. Keep keyof T and filter with as, or use Pick, which is homomorphic.
• Expecting -? to keep undefined. On a homomorphic type it removes the undefined the optional added (Required<{ a?: string }> is { a: string }).
• Using `get${K}` where K can be symbol or number. Template literal placeholders only accept string | number | bigint | boolean | null | undefined (checked: `x${symbol}` is TS2322), so write string & K, as the handbook does.
• Assuming mapped types are "deep". They touch only the first level; nested objects need recursion.