TLDR

This PR enhances reverse mapped types capabilities providing users with the ability to enable EPC (Excess Property Checking) on type parameters inference sites.

Background

This PR has come up trying to find a way to solve some problems discussed in #55645 and #55644, which are a simplification of what"s going on in this PR from XState. In those cases the usual type parameters inference behaviour is not enough, mainly because it disables EPC (Excess Property Checking).

FIxes #55927

Idea

Reverse mapped types are a powerful tool. Currently TypeScript is able to reverse three kind of mapped types:

1. a homomorphic mapped type { [P in keyof T]: X }
2. a mapped type { [P in K]: X }, where K is a type parameter
3. a mapped type with an union constraint, as long as the union contains one of the constraints of the previous cases

This PR adds a fourth case: a mapped type with an intersection constraint, as long as the intersection contains one of the constraints of the previous cases.

While the union constraint could be seen as a way to force the presence of some properties, the intersection one could be seen as a way to prevent the presence of extra properties.

Examples

Example N. 1

Here the type parameter T is now inferred, by reversing the mapped type, as { bar: 1; baz: "a"; record: { a: number; b: number } }, instead of falling back to its constraint Foo. The properties of the parameter s are constrained to be exactly the ones already declared in Foo, so EPC comes into play if the argument contains extra properties:

interface Foo {
  bar: number;
  baz: string;
  record: Record<any, any>;
}

// the intersection constraint on `K` is `keyof T & keyof Foo`
declare function useFoo<T extends Foo>(s: { [K in keyof T & keyof Foo]: T[K] } ): T

useFoo({ 
  bar: 1,
  baz: "a",
  record: { a: 1, b: 2 },
  extra: 123, // <-- EPC error
})

In this way you get both inference and EPC check!
Note that the extra property is stripped away from T because it wouldn"t survive the action of the mapped type anyway.

Example N. 2

In the following example, inspired from #12936, is the type parameter U the one that gets inferred by reversing the mapped type. It is inferred as { x: 1; y: "y"; record: { a: number; b: number } } instead of falling back to its constraint. As before, no extra properties are allowed so we get an EPC error on z that will always be stripped away from the inferred type:

// the intersection constraint on `K` is `keyof U & keyof T`
const checkType = <T>() => <U extends T>(value: { [K in keyof U & keyof T]: U[K] }) => value;

const checked = checkType<{x: number, y: string, record: Record<any, any> }>()({
  x: 1,
  y: "y",
  record: { a: 1, b: 2 },
  z: "z", // <-- EPC error
});

Tests

Two tests files have been added:

1. reverseMappedTypeIntersectionConstraint, in which the main capabilities brought by this PR have been tested, although I must admit I don"t think there are enough test cases
2. reverseMappedTypeLimitedConstraint, in which the stripping behaviour on the inferred type parameters has been written down, but it is somehow subsumed by the previous test and for this reason it might be deleted altogether

A note on EPC

What"s good about this PR is the fact that it lets the user enable EPC on type parameters without fundamentally change how TS treats type parameters inference. It"s just a nice side effect of enhancing reverse mapped types" capabilities.

Remarks

This PR may help with some cases presented in #12936 as well.

#55794 could help improving what happens when a const type parameter is used, because there are some inconsistencies with readonly modifiers.

Acknowledgements

Huge thanks to @Andarist for always having my back 😄.