James Routley

Sat, Dec 21, 2024

I’ve been doing a lot of work in TypeScript lately, and with that I’ve spent quite a bit of time learning more about its type system. TypeScript is a wonderfully advanced language though it has an unfortunately steep learning curve; in many ways it’s the complete opposite of Go.

One confusing thing about TypeScript is that it doesn’t always infer the most precise type possible. As an example:

// name is of type "Jerred"
const name = "Jerred";

// person1 is of type { name: string }
const person1 = {
  name: "Jerred",
};

// person2 is of type { readonly name: "Jerred" }
const person2 = {
  name: "Jerred",
} as const;

Why is the name of person1 of type string and not the literal "Jerred"? Because the object could be mutated to contain any other string.

What happens when I want to pass those objects to a function that requires name to be "Jerred"?

function handleJerred(name: "Jerred") {
  // do something
}

// these are okay
handleJerred(name);
handleJerred(person2.name);

handleJerred(person1.name);Argument of type 'string' is not assignable to parameter of type '"Jerred"'.

As we’d expect, the types don’t match up. The most obvious way is to annotate the variable declaration with the expected type:

const person1: { name: "Jerred" } = {
  name: "Jerred",
};

// okay
handleJerred(person1.name);

We could also use the satisfies keyword. This keyword is a bit esoteric and not very common, but it comes in handy in some scenarios where you’d otherwise pull your hair out.

Here’s a quick example just to show the syntax:

const person1 = {
  name: "Jerred",
} satisfies { name: "Jerred" };

// okay
handleJerred(person1.name);

satisfies is an alternative to an explicit variable type annotation. It tells TypeScript that your assignment should be at least assignable to the provided type. It’s kind of like a type-safe way to cast values.

The benefit of satifies over an variable type annotation is that it lets TypeScript infer a more specific type based on the value provided. Consider this scenario:

type Person = {
  name: string;
  isCool: boolean;
};

function coolPeopleOnly(person: Person & { isCool: true }) {
  // only cool people can enter here
}

const person1: Person = {
  name: "Jerred",
  isCool: true,
};

// okay, so we need to say that `isCool` is true
coolPeopleOnly(person1);Argument of type 'Person' is not assignable to parameter of type 'Person & { isCool: true; }'.
  Type 'Person' is not assignable to type '{ isCool: true; }'.
    Types of property 'isCool' are incompatible.
      Type 'boolean' is not assignable to type 'true'.

// and we also need to include the name field...
const person2: { isCool: true } = {
  name: "Jerred",Object literal may only specify known properties, and 'name' does not exist in type '{ isCool: true; }'.
  isCool: true,
};

const person3: { name: string; isCool: true } = {
  name: "Jerred",
  isCool: true,
};

coolPeopleOnly(person3);

A simpler solution is to use satifies:

const person = {
  name: "Jerred",
  isCool: true,
} satisfies Person;

coolPeopleOnly(person);

TypeScript will ensure that your value is assignable to your type. The type of the assigned variable will be made based on the type of the value instead of the type provided to satisfies.

This really comes in handy when you want to ensure that TypeScript is being as specific as possible.

`satisfies` is my favorite TypeScript keyword (2024)