🔓 Intent to use: checker.isTypeAssignableTo

[JoshuaKGoldberg]

Overview

Long have we in the TypeScript tooling community spoken of this in hushed tones: microsoft/TypeScript#9879, using a type relationship API in TypeScript. A type relationship API would most notably let us determine reliably whether a type is assignable to another type. That ability would be fantastic for a slew of bugs and feature requests: see microsoft/TypeScript#9879 (comment) for a list of over a dozen in this repo alone.

TypeScript hasn't yet exposed a type relationship API publicly out of concern for stability and whether the limited set of APIs we're requesting will be sufficient for most or all use cases. Which is very reasonable: the type checker is very complex and has lots of caching internally that can be difficult to predict without deep knowledge of TypeScript program implementations. It's a risky thing to expose these APIs and doubly risky to make them part of a versioned public API.

But! Over the last few years, we've seen several community projects make use of the private checker.isTypeAssignableTo API: Arktype, TypeStat, and an assortment from querying public repos on Sourcegraph. This gives us confidence that at least the specific checker.isTypeAssignableTo API is roughly stable enough for us to at least try out. Per this thread in the TypeScript Discord asking about using checker.isAssignableTo using it is not considered egregious at first glance. Furthermore, seeing how ecosystem projects use the private checker.isTypeAssignableTo may even help inform a more formal TypeScript type relationship API later on.

Fun fact: isTypeAssignableTo has been available on TypeChecker objects since roughly TypeScript 3.7.

3.6.5 has undefined
3.7.7 has [Function: isTypeAssignableTo]

// index.js
import { $ } from "execa";

for (const version of ["3.5", "3.6", "3.7", "3.8"]) {
  await $`npm i typescript@${version}`;
  await $({ stdio: "inherit" })`node ./check.js`;
}

// check.js
import ts from "typescript";

const program = ts.createProgram({
  rootNames: [],
  options: {},
});

console.log(ts.version, "has", program.getTypeChecker().isTypeAssignableTo);

Here is our intent in typescript-eslint:

1. Do nothing with this information for our current major version, v6 v7
2. Once v8 is released, we'll add isTypeAssignableTo to the allowlist of private APIs we feel comfortable using, and unblock all issues marked as blocked
3. If at any point this breaks, we'll do our best to figure out what went wrong and contribute fixes back to TypeScript as needed

🤞 here's hoping it all works out well!

If there are any concerns with this approach or ideas for new lint rule bugfixes or features not yet mentioned in microsoft/TypeScript#9879 (comment), we'd love to hear them!

---

Edit 1 (November 20th, 2023): microsoft/TypeScript#56448 was opened by our friend @jakebailey to make the API public. If it's merged and released, we can close this discussion as irrelevant. 🚀

Edit 2 (December 11th, 2023): microsoft/TypeScript#56448 was merged into TypeScript! Beautiful. To play it safe, I'll wait until a TypeScript RC is released before closing this discussion out.

Edit 3 (February 27th, 2024): Replaced 'v7' with 'v8' as we injected a small v7 version before what was previously going to be our next major.

[JoshuaKGoldberg]

https://devblogs.microsoft.com/typescript/announcing-typescript-5-4-rc 🚀

Looks like we can consider checker.isTypeAssignableTo as ready once v8 is released!

[JoshuaKGoldberg]

Now that typescript-eslint@v8 is released, this is ready to go!