(You can find a video version of this article on YouTube! 📺)
The problem
Imagine you're faced with the following problem:
You have a type City
that can be either CityName
or CityCoordinates
:
type City = CityName | CityCoordinates;
CityName
is a string representing one of the specified cities:
type CityName = "New York" | "Mumbai" | "Lagos";
CityCoordinates
is an object with x
and y
properties denoting the coordinates of your city:
type CityCoordinates = {
x: number;
y: number;
};
And the User
type has birthCity
and currentCity
, both of which are you type City
:
type User = {
birthCity: City;
currentCity: City;
};
Then, you want to create a new variable user
that adheres to the User
type.
You want to assign "Mumbai"
to the birthCity
property (that's of the type CityName
) and { x: 6, y: 3 }
to the currentCity
property (that's of the type CityCoordinates
).
What you would normally do is something like this 👇
const user: User = {
birthCity: "Mumbai",
currentCity: { x: 6, y: 3 },
};
That's all well and good and, as of TypeScript 4.8 of less, the only way to make sure that the user
variable matches the shape of the User
type.
Now, say you want to make the birthCity
property of the user
variable uppercase.
If you were to do that, however, you'd make TypeScript upset and get an error:
// yields this TypeScript error 👇
// Property 'toUpperCase' does not exist on type 'City'.
// Property 'toUpperCase' does not exist on type 'CityCoordinates'.
user.birthCity.toUpperCase();
The way that TypeScript sees the birthCity
property is that it can be either CityName
or CityCoordinates
.
It doesn't "know" that you want the user
variable to have the CityName
type for the birthCity
and the CityCoordinates
for the currentCity
.
satisfies
to the rescue
Before the satisfies
keyword was introduced, there wasn't a good way to achieve this.
More specifically, it wasn't possible to both
- ensure that a variable matches the specified type
- make TypeScript infer a more specific type based on the values provided to this variable
Now that we've got the satisfies
keyword, this very thing is now possible!
The syntax is as follows 👇
const user = {
birthCity: "Mumbai",
currentCity: { x: 6, y: 3 },
} satisfies User
The inferred type of the user
variable is going to be 👇
{
birthCity: "Mumbai";
currentCity: {
x: number;
y: number;
}
}
This will enable us to access string
-specific methods (like .toUpperCase()
) on the birthCity
property and access the x
and y
number properties on the currentCity
variable 👇
// we can call `toUpperCase`
user.birthCity.toUpperCase();
// ...and we can access the `x` (or `y`) properties
// and call `number`-specific methods on them
user.currentCity.x.toFixed(2);
And, on top of that, if we were to assign a value that doesn't match the User
type to the user
variable, we would get protected from type errors 👇🏻
const user = {
// assigning "Beijing" yields this error 👇
// Type '"Beijing"' is not assignable to type 'City'
birthCity: "Beijing",
currentCity: { x: 6, y: 3 },
} satisfies User
In conclusion, with satisfies
we can get the best of both worlds. Type safety saves us from runtime errors and powerful type inference gives us most specific types for free.
Source code
You can find the source code for this tutorial on Typescript Playground.
If you liked this tutorial, you can also check out and subscribe to my YouTube channel. Or/and subscribe to my newsletter to get notified when I publish new articles on my website!
Top comments (1)
Finally an easy explanation of satisfies. Thank you.