Deprecate homomorphic mapped type over primitive

🔍 Search Terms

homomorphic mapped primitive

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

I would like homomorphic mapped types over primitives to emit a warning if the base type is not an object type. An explicit conditional type Foo<T> = T extends object ? { [K in keyof T]: ...} : T can be used to recover the pre-existing behavior. This should be mentioned in the warning message.

Homomorphic mapped type over primitives has surprising behavior that bears mention in the FAQ:

• This mapped type returns a primitive type, not an object type.
  • Mapped types declared as { [ K in keyof T ]: U } where T is a type parameter are known as homomorphic mapped types, which means that the mapped type is a structure preserving function of T. When type parameter T` is instantiated with a primitive type the mapped type evaluates to the same primitive.

This behavior is surprising since:

1. It is not referentially transparent; that is, replacing a type parameter with its value does not result in the same type
2. Although a mapped type may be assignable to the original type, it may specifically not be, e.g. {[k in keyof T]: never} whereas it always is in the case of primitives.
3. The expression keyof T has surprising behavior on primitive types, differing substantially from object types.
4. The syntax of a mapped type visually suggests an object-like type, which is incorrect when mapping over null.

📃 Motivating Example

type NullValued<X> = {[k in keyof X]: null};
type Okay = NullValued<{x:1, y:2}>; // {x:null, y:null}
type Oops = NullValued<number>; // oops! This is `number`, which is likely not what you expected

💻 Use Cases

1. What do you want to use this for?
2. What shortcomings exist with current approaches?

• You have to know about homeomorphic mapped types and anticipate this corner case.

3. What workarounds are you using in the meantime?

• A type guard type Foo<T extends object> = { [K in keyof T]: ...} guards against the current behavior.
• A conditional type Foo<T> = T extends object ? { [K in keyof T]: ...} : T makes the current behavior explicit.

Start with the motivating NullValued example and the FAQ passage in the issue; no implementation file or test is named. Done means homomorphic mapped types over primitive bases produce the requested warning, and the warning explains the explicit conditional workaround while the surprising behavior is documented in the FAQ.