Proposal: repurpose "is" operator for a narrowing version of "satisfies"

[michaelboyles]

🔍 Search Terms

satisfies with narrowing
narrowing literals
satisfias, satisfiesas, sassafras

✅ 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

A narrowing version of the satisfies operator

type Animal = "cat" | "dog";
const animal = "cat" is Animal;
/// ^? = Animal

📃 Motivating Example

Consider an API where the return type is influenced by the input type. For example, this simplification of Tanstack Form (I'm not a contributor to it, but I'm developing something similar).

function useForm<T>(defaultValues: T): T {
    return /*something*/;
}

const values = useForm({
    animal: "cat"
});

The type inferred from animal here is string.

This works fine if animal is a text input in our form, but what if we want it to be an enumeration, e.g. <select>, and also retain some compile-time typechecking? e.g. we want to prevent this

values.animal = "red"

satifies will error if the initial value is not valid, but it doesn't narrow the type:

// #1
const values = useForm({
    animal: "cat" satisfies Animal
});
// typeof values["animal"] = string

as achieves the equivalent of narrowing here, but it masks some errors:

// #2
const values = useForm({
    animal: "red" as Animal // no error
});

I propose to repurpose the existing is keyword. Could use another keyword; bikeshed it later.

const values = useForm({
    animal: "cat" is Animal
});

This would produce a compiler error if the left hand side was not an Animal (like satifies), but additionally narrow the type to Animal.

💻 Use Cases

What shortcomings exist with current approaches?

A more natural flow of the code is disrupted; the field can't be declared inline.

What workarounds are you using in the meantime?

This one is okay, but somewhat disrupts the flow of reading top to bottom.

// #3
const initialAnimal: Animal = "cat";
const values = useForm({
    animal: initialAnimal,
    plainString: "a",
    plainNumber: 1
});

This one requires declaring the entire type separately. Also there may be many more type args than just the data shape. This is the case in Tanstack Form. You'd need useForm<FormValues, Blah, Blah, Blah, ...>;

// #4
type FormValues = {
    animal: Animal
}
const values = useForm<FormValues>({
    animal: "cat"
});

This is probably what I find myself reaching for, but as with #4 requires declaring the entire type

// #5
type FormValues = {
    animal: Animal
    plainString: string
    plainNumber: number
}
const initialValues: FormValues = {
    animal: "cat",
    plainString: "",
    plainNumber: 0
}
const values = useForm(initialValues);

[RyanCavanaugh]

You're widening the type here, not narrowing it.

[jcalz]

You might want to define Animal for us, and provide a Playground link with everything we need to see the issue (if not the solution with the unsupported syntax). Maybe like this:

declare function useForm<T>(defaultValues: T): T;
type Animal = "ant" | "bee" | "cat" | "dog" | "elk" | "fox" | "gnu" | "hog";
const values = useForm({ animal: "cat" satisfies Animal });
//    ^? const values: { animal: string }

And then, I believe you're trying to propose what has been called the satisfias operator (also known as satisfiesas and sassafras),

#61789 (comment)
#51853 (comment)

since you want x is T to be the equivalent of x satisfies T as T so you get both the check and then the widening/narrowing-or-whatever-is-happening in the above example (it is quite odd that "cat" satisfies Animal above does not actually narrow to Animal or "cat" but somehow passes the check while T is inferred as string. Almost seems like a TS bug):

const values2 = useForm({ animal: "cat" satisfies Animal as Animal });
//    ^? const values2: { animal: Animal }

Is that right? If so I (still) don't know if there is an official already-open issue for this.

[michaelboyles]

@jcalz Yep, you got it spot on. Sorry for the omission (edited now).

Just on the subject of x satisfies T as T, the shortcomings of that approach is not just the duplication, but it's also vulnerable to typo bugs in the form x satisfies T as U, e.g. "cat" satisfies Animal as Color. Really as is a stronger assertion than is desirable for this use-case.

[mkantor]

I just stumbled across #56235 which I think this issue is a duplicate of (just with a different proposed keyword).

Maybe that's the already-open issue that @jcalz was looking for?

[michaelboyles]

@mkantor Yep, looks the same. Good job digging it out.

Feel free to close this one if it helps keep everything together. I do think my description and example are probably better though (but I would think that)