Support `satisfies` as a constraint on a function's generic type parameter

[rsslldnphy]

🔍 Search Terms

"satsifies", "satisfies generic parameter".

i found two similar/related feature requests, but they felt different enough to warrant being a separate feature request:

• Support satisfies operator on functions #51556
• Support satisfies in type declaration #52222

✅ 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

Currently, from what I can tell, is not possible to mimic the behaviour of satisfies on a function's generic type parameter - i.e. to define a function with a generic parameter that allows inference of a literal type that conforms to that generic parameter, while still benefitting from excess property checking. Because the only option for a generic type parameter is extends, there's no way (that I can see) to prevent extra keys in the inferred generic type.

📃 Motivating Example

A bare bones example of what this change would make possible:

type Foo = { a: number };

const foo = <T extends Foo>(x: T) => x;

foo({ a: 1, wrong: 2 }) // typechecks, but i don't want it to

foo({ a: 1, wrong: 2} satisfies Foo) // causes the type error i want

What I would really like to be able to write:

type Foo = { a: number };

const foo = <T satisfies Foo>(x: T) => x;

foo({ a: 1, wrong: 2 }) // causes the type error i want

💻 Use Cases

1. What do you want to use this for?

The reason I want this functionality is that I'm writing an ORM and would like to restrict the keys passed to the create function to only the keys present in the model. To be clear I do not need a runtime check and any extra keys actually in the model are fine. The reason I want this feature is to provide a good experience when writing code like this with literal types:

class DB<Models extends BaseModels> {
    public async create<
        M extends ModelName<Models>,
        P extends CreateParams<Models, M>,
    >(m: M, params: P): Promise<CreateResult<Models, M, P>> {
        // ...omitted for brevity
    }
    // ...omitted for brevity
}

db.create("post", {
    data: {
        title: "hello",
        content: "it me",
        authorId: uuid.v4(),
        // @ts-expect-error field does not exist
        wrong: 2,
    },
    returning: ["id"],
// this causes a type error if `satisfies` is used, but does not cause a type error if it is not
} satisfies CreateParams<typeof db.models, "post">);

3. What shortcomings exist with current approaches?

It is only possible to use satisfies at the call site of a function, and must be used at every call site, rather than being specified as part of the function's generic type parameter.

5. What workarounds are you using in the meantime?

I have not been able to find a workaround. If there is one, I would be very happy to hear it! If not I think the only option is to use satisfies at every call site.

[Andarist]

You might want to take a look into the recent improvement from #55811

type Foo = { a: number };

const foo = <T extends Foo>(x: { [K in keyof T & keyof Foo]: T[K] }) => x;

foo({
  a: 1,
  // Object literal may only specify known properties, and 'wrong' does not exist in type '{ a: 1; }'.(2353)
  wrong: 2,
});

[rsslldnphy]

nice!! thank you, that gives me the behaviour that i need. it's pretty complex to represent so a simpler way to do it via satisfies would still be much appreciated.

i haven't got it fully working, am still getting some weird errors with other (optional) keys in the constrained type seeming to lose some type information, but this is a big step forward, and once i've managed to put together a minimal reproduction of the issue i'm now facing i'll ask on stack overflow. thanks again @Andarist !

[Andarist]

It has currently some limitations (like #56910 ). If you are hitting some other thing - please let me know. If you provide a repro I could take a look at it.

[rsslldnphy]

ok i think i've got it working with a fairly monstrous type. forgive the messiness as i'm pretty new to (relatively) more advanced typescript stuff. if there are ways to simplify this or any obvious problems i'd really appreciate a pointer!

i found i had to treat required and optional properties separately, but maybe there's an easier way to do this?

type OptionalKeys<T extends Record<string, unknown>> = {
    // eslint-disable-next-line
    [P in keyof T]: {} extends Pick<T, P> ? P : never;
}[keyof T];

type RequiredKeys<T extends Record<string, unknown>> = {
    // eslint-disable-next-line
    [P in keyof T]: {} extends Pick<T, P> ? never : P;
}[keyof T];

type Satisfies<T, Base> =
    // recur if both the generic type and its base are records
    T extends Record<string, unknown>
        ? Base extends Record<string, unknown>
            // this check is to make sure i don't intersect with {}, allowing any keys
            ? (keyof T & RequiredKeys<Base> extends never
                  ? unknown
                  : {
                        [K in keyof T & RequiredKeys<Base>]: Satisfies<
                            T[K],
                            Base[K]
                        >;
                    }) &
                   // this check is to make sure i don't intersect with {}, allowing any keys
                  (keyof T & OptionalKeys<Base> extends never
                      ? unknown
                      : {
                            [K in keyof T & OptionalKeys<Base>]?: Satisfies<
                                T[K],
                                Base[K]
                            >;
                        })
            // if the generic type is a record but the base type isn't, something has gone wrong
            : never
        : T extends (infer TE)[]
          ? Base extends (infer BE)[]
              ? Satisfies<TE, BE>[]
               // if the generic type is an array but the base type isn't, something has gone wrong
              : never
          // the type is a scalar so no need to recur
          : T;

which leads to desired behaviour:

type Foo = { a: { b?: number }[] };

const foo = <T extends Foo>(x: Satisfies<T, Foo>) => x;

foo({ a: [{}] }); // typechecks
foo({ a: [{ b: 3 }] }); // typechecks
foo({ x: 2 }); // error
foo({ a: [{}], x: 2 }); // error
foo({ a: [{ b: 2, x: 3 }] }); // error
foo({ a: [{ x: 3 }] }); // error

EDIT - ignore this, i thought it was working but it isn't (in my codebase specifically), in a way that i haven't been able to minimally reproduce yet.

[fatcerberus]

I'm a little confused about the use case honestly - if you don't want subtypes, why is the function generic? Also note that EPC is more of a lint check than a proper type rule, and it's very easy to sneak extra properties in simply by, e.g., assigning the object literal to a variable first. See #12936

[rsslldnphy]

@fatcerberus the specific use case i want this for is for an ORM that allows users to specify the types of their models such that queries return strongly typed results. the aim is for users to get useful type hints when writing queries as literal objects. For example, in the below code:

const result = await db.create("post", {
    data: { title: "hello", content: "it me", authorId: "123", wrong: 2 },
    returning: ["authorId"],
});

db is a generically typed representation of the user's database schema, which is aware of what models it contains and what field each model has. so typescript is able to know that "title", "content", and "authorId" are all valid fields on the "post" model. "wrong" however is not. what i'm trying to get to is a situation where typescript will show the "wrong" property as a type error, to let the user know they've done something wrong. this is exactly the behaviour you get if you use satisfies at the call site:

const result = await db.create("post", {
    data: { title: "hello", content: "it me", authorId: "123", wrong: 2 },
    returning: ["authorId"],
} satisfies CreateParams<Models, M>);

but ideally i'd like to build this check into the function itself. it's fine to sneak extra properties in, they will be safely ignored. the purpose of the typing here is only to help the user of the library write correct code when writing literal queries.

there's clearly something very odd going on with the types in my project though, they're behaving weirdly in a way i've yet to figure out how to replicate in a ts playground

EDIT - so yes, as you say, the intention is for it to be more of a lint check than a proper type rule. if there's an alternative / better way to achieve this i'd really appreciate a pointer!

[jcalz]

This is essentially a duplicate of #12936, since we're not looking for all of satisfies's behavior, just excess property checking. Until and unless TS supports this, it's much easier to write code that doesn't care about excess properties than it is to write code that forces TypeScript to care about them. Especially because it's always going to be trivial to work around such code, by just someone widening the value before passing it.

I don't understand why you'd need this if you just want the user to write correct code, though. IntelliSense should prompt for the known keys, and not for unknown ones. Why do you need an error for unknown keys?

[rsslldnphy]

@jcalz i'm not sure this is a duplicate, as i do want all of satisfies' behaviour (at least as i understand it): excess property checking AND the preservation of literal types - both are necessary.

if i didn't need the preservation of literal types, i wouldn't have to use a generic, and excess property checking would work fine. if there's a better/simpler way to achieve both those things i'd be v keen to take a different approach!

you're right that intellisense will prompt for the known keys and not unknown ones, but if the user types or copy/pastes an incorrect one there will then be no feedback to them that they've made a mistake. basically the reason i want an error for unknown keys is the same reason i find them useful when not using a generic - they let me know when i've made a mistake!

i feel like this is uncontroversial in the case of normal excess property checking, so the fact it seems controversial in this case is suggesting to me that i must be fundamentally misunderstanding or missing something, but i don't know what.

[RyanCavanaugh]

I don't understand the distinction either. Either you're subtyping or you're not. If you don't want extra-keys subtyping, the feature you need is exact types. satisfies and extends do the same thing - check that the right operand is a subtype of the left operand.

[jcalz]

There's already const type parameters for literal types.

Excess property checking is only supposed to be "normal" in cases where TS promptly forgets the excess property. The mistake isn't "there's an extra property" but "there's a property TS can't possibly remember". So T extends Foo won't complain against excess properties on T because T will hold the information. Excess property checking is similar to having exact types, and there's overlap, but it's not the same feature. Even with "normal" excess property checking, nothing stops

interface Foo {x: string}
interface Bar extends Foo {y: string}
const bar: Bar = {x: "",y: ""}
const foo: Foo = Bar; // <-- nothing can ever stop this

That's allowed because bar will remember y, even though foo will not. Only const foo: Foo = {x: "", y: ""} is an error.

Without #12936, there's no way to say universally that excess properties are "a mistake" by their mere presence.

With the current state of TS, it's going to be much easier to get out of the mindset that excess properties are "a mistake" and get into the mindset that it's just how structural typing works. That lets you write code that doesn't explode in the face of excess properties and move on, instead of struggling to represent a concept TS just doesn't know how to deal with.

[RyanCavanaugh]

Like, let's say this operator existed

type Foo = { a: number };

const foo = <T satisfies Foo>(x: T) => x;

foo({ a: 1, wrong: 2 }) 

What would happen?

During inference we'd see a candidate { a: number, wrong: number } for T, so would infer T to be that type. Then we'd check that { a: number, wrong: number } is a subtype of { a: number }. It is, because extra keys are allowed in subtyping. So the call succeeds.

It's the same as if you had written this:

type Foo = { a: number };
const p = { a: 1, wrong: 2 };
p satisfies Foo; // it does

satisfies does not have special additional type behavior that extends doesn't

[rsslldnphy]

I appreciate your time with this - going to make one last attempt to try to articulate where my confusion is. Yes, once something is assigned to a variable, all bets are off. However, both satisfies and calling a normal non-generic function behave differently depending on whether they are given a variable or a literal value. While with a generic there is only one behaviour.

Extending your example a bit (here's a playground link):

type Foo = {a: number}

// Satisfies works differently given a literal vs a variable

const x = {a: 3, b: 4 } satisfies Foo // it doesn't

const y = {a: 3, b: 4} as const;

y satisfies Foo // it does

// --------------

// Calling a function works differently given a literal vs a variable

const f1 = (x: Foo) => x;

f1({a: 3, b: 4 }) // doesn't work

f1(y) // this works fine

// --------------

// However, calling a generic function works the same in both cases

const f2 = <const T extends Foo>(x: T) => x;

f2({ a: 3, b: 4 }) // works - and i want a way to stop it from working

f2(y) // also works - and **should continue to work**

I guess my feature request comes from the (perhaps misplaced) intuition that it should be possible for there to be symmetry here, and my understanding of satisfies being different to extends comes from the lack of symmetry w/r/t excess property checking. If satisfies didn't do excess property checking I wouldn't have this expectation.

[RyanCavanaugh]

You can do this:

const f2 = <const T extends Foo>(x: NoInfer<T>) => x;

Your objection will be "But I still want to use the more-specific type information of T", and (without exact types) extra keys are part of that more-specific type information

[rsslldnphy]

Ok I'm giving up now but just to say one last time that I do not want exact types. I want a way to tell Typescript to be smarter with excess property checking.

Which I think aligns pretty well with what you wrote on the exact types issue:

For the most part where people want exact types, we'd prefer to fix that by making EPC smarter.

This is me wanting a way to make EPC smarter! The EPC I get with satisfies is very helpful, and I'd like the opportunity to use it in more contexts - that's it.

As I say, I appreciate your time. I'm frustrated that I didn't come to an understanding as to why this isn't a good idea, but maybe as I learn more I will.