Proposal: Type Relationship API

[weswigham]

They type checker has no public API for checking type relationships or for looking up types in a given scope. This can make writing semantic-analysis informed lint rules very difficult (either because you need to replicate a lot of logic, or because you simply don't have enough information). Since tslint enabled semantic checks we now have a popular consumer who would very much like to be able to perform meaningful semantic comparisons (See this rule for instance).

Proposal

A small new set of public API methods on the type checker:

interface TypeChecker {
  isIdenticalTo(a: Type, b: Type): boolean; // Exposes internal identity relationship
  isSubtypeOf(a: Type, b: Type): boolean; // Exposes internal structural subtype relationship
  isAssignableTo(a: Type, b: Type): boolean; // Exposes internal assignable relationship
  isComparableTo(a: Type, b: Type): boolean; // Exposes internal comparable relationship
  isInstantiationOf(a: GenericType, b: GenericType): boolean; // While not an internal relationship, it is a straightforward semantic question to ask an answer which requires internal APIs to answer

  lookupGlobalType(name: string): Type; // Looks up a global symbol named "name" with meaning SymbolFlags.Type (Identical to getGlobalType but without the expected arity based return value) - returns unknownType on failure
  lookupTypeAt(name: string, position: Node): Type // Resolve a symbol lexically at the position specified with meaning SymbolFlags.Type (identical to resolveName, but with less levers) - returns unknownType on failure

  getAnyType(): IntrinsicType;
  getStringType(): IntrinsicType;
  getNumberType(): IntrinsicType;
  getBooleanType(): IntrinsicType;
  getVoidType(): IntrinsicType;
  getUndefinedType(): IntrinsicType;
  getNullType(): IntrinsicType;
  getESSymbolType(): IntrinsicType;
  getNeverType(): IntrinsicType;
  getUnknownType(): IntrinsicType;
  getStringLiteralType(text: string): StringLiteralType; // When numeric literal types merge, they should have a similar endpoint
}

While this isn't a complete set of APIs for manipulating the type checker (I've left off an API to programatically create new types for comparison), it is enough to do meaningful analysis with existing types in the compilation without resorting to brittle (or often wrong) syntax-based solutions.

[weswigham]

cc: @ahejlsberg @mhegazy @rbuckton @vladima

[kitsonk]

I was discussing something like this today with @novemberborn in that sometimes we aren't sure why the types are what they are at a particular point, especially when they are contextually inferred.

Would it be possible to also consider potentially offering up additional meta data that would explain the type at a particular node (sort of like good ole SQL "explain plan")?

[mhegazy]

Would it be possible to also consider potentially offering up additional meta data that would explain the type at a particular node (sort of like good ole SQL "explain plan")?

can you elaborate on the scenario here? there are multiple ways the compiler can find a type. though, all is specified by the spec, the information is not persisted any ways. what we know is a type.

[ghost]

Is there any progress on this? It would be incredibly useful to have. Just an isTypeAssignableTo would be great. Right now the only option is to link to a customly patched version of TypeScript.

[raveclassic]

What's the status of this API? It is needed for checking yields in redux-saga (described in #19602)

Agree with @samvv - isTypeAssignableTo would be enough to check lhr and rhs of a yield expression with a custom type-based comparison which is needed sooo badly.

UPD: Have found #9943

[ibezkrovnyi]

As PR #9943 is closed now, is it possible to export only isTypeRelatedTo and *Relation which should cover @raveclassic and @samvv cases, also with identityRelation it will cover:

1. tslint rule no-inferrable-type

   where only primitive number, string and boolean types are supported

2. tslint-consistent-codestyle no-unnecessary-type-annotation (@ajafff)

   where typeToString is used, however it often gives false negatives, e.g. in cases like { x: number, y: number } type is not equal to { y: number, x: number }

3. fimbullinter/wotan no-useless-assertion and prefer-for-of
4. no-inferrable-return-types

also it will cover few closed issues, where authors were waiting for PR #9943 like:

• Expose isTypeRelatedTo in the compiler API #17917
• Assignability checks in API #13502

also at least partly it should cover this request: #11728 (comment)

also it will close a few more closed by bot issues.

@weswigham @mhegazy

[rictic]

As another use case, this would enable type checking HTML template systems such as lit-html. For this code:

html`<date-picker .date=${currentDate}></date-picker>`

We'd want to assert that typeof currentDate is assignable to ElementTagNameMap['date-picker'].date.

This is applicable to many template systems.

[lukewis]

Would love to see some baby steps that could occur in this area. It seems like the tooling that would be enabled by having APIs like this would be tremendous! As @ahejlsberg pointed out, it's hard to know where to stop with these APIs, but I liked @weswigham's suggestion in the original pull request #9943 about separating the "type comparison" apis from the "type building" apis. It seems like the "type building" apis is a big task, but the type comparison apis might be a smaller effort?

[rictic]

Just chatted with @octref about improving the custom element editing experience. I think the need for these APIs is showing up across the editing ecosystem as every template system provider eventually runs into the need to type check templates.

He pointed out that the Vue LSP is working on implementing type checking of templates by doing code generation, running the typescript compiler over the generated code, then mapping diagnostics on that code back to the original source: https://github.com/vuejs/vetur/pull/681/files

Having a type relationship API would make this sort of work simpler, faster, and more robust.

[lgenzelis]

Just trying to keep this alive 😅 It would be immensely useful to have at least the isTypeAssignableTo method available to be used from typescript-eslint. My use case is a rule that prevents dangerous type assertions (i.e., that allows to do 'a' as string | number but not string as 'a'. See typescript-eslint/typescript-eslint#7173

[JoshuaKGoldberg]

Fun fact: https://github.com/JoshuaKGoldberg/TypeStat has been using TypeScript's internal isTypeAssignableTo for over 4 years now (JoshuaKGoldberg/TypeStat@0129b6d). It does so by rewriting typescript.js on disk. Over those >4 years, TypeStat has never had any issue with the API changing or having bugs - stateful or otherwise.

Here's a rough list of the typescript-eslint / area issues & PRs that are blocked or restricted on a TypeScript type assignability API:

• Rule enforcing typeAnnotation on a complex query is correct eslint-community/eslint-plugin-eslint-plugin#340
• Feature: add a new assertion that uses assignability checking JoshuaKGoldberg/eslint-plugin-expect-type#18
• Use union types for all common classes of AST nodes #54148 (comment)
• Rule proposal: Strict interface implementation typescript-eslint/typescript-eslint#277
• Enhancement: Rule to prefer type annotation over type assertion when possible typescript-eslint/typescript-eslint#709
• Bug: [prefer-readonly] autofixer doesn't add type to property that is mutated in the constructor typescript-eslint/typescript-eslint#1056
• Bug: [prefer-reduce-type-parameter] unfixable reporting typescript-eslint/typescript-eslint#3440
• Enhancement: [no-unnecessary-type-arguments] Report inferred required types typescript-eslint/typescript-eslint#4978
• Rule proposal: prevent comparing object types typescript-eslint/typescript-eslint#5647
• Enhancement: [consistent-type-assertions] Prefer type annotation over assertion for arrays typescript-eslint/typescript-eslint#6374 (in that it presents a known edge case bug, see PR description)
• Rule proposal: disallow unused return types typescript-eslint/typescript-eslint#6442
• Rule proposal: no-unsafe-type-assertion typescript-eslint/typescript-eslint#7173
• Rule proposal: Enforce related types for getter and setter pairs typescript-eslint/typescript-eslint#7236
• Bug: [no-unnecessary-type-assertion] Does not work with enums typescript-eslint/typescript-eslint#7652
• Enhancement: [no-redundant-type-constituents] Use assignability checking for redundancy checks typescript-eslint/typescript-eslint#7742
• (edit 10/19) Rule proposal: no unchecked casts out of a potentially nullish type typescript-eslint/typescript-eslint#7757

Note that this is definitely incomplete. For many of the use cases we could have filed issues for, people didn't because they knew it was blocked on #9879. typescript-eslint/typescript-eslint#7742 is an example.

To my knowledge, we've almost never (perhaps truly never) had a need for a relationship API other than assignability. We're trying to be good citizens and not taking the TypeStat strategy of cracking open TypeScript's files for the isTypeAssignableTo API. But this is really painful.

Edit: @jakebailey and I just noticed that checker.isTypeAssignableTo does exist now - but it's marked as internal. So although libraries like TypeStat no longer need to manually rewrite files to get to isTypeAssignableTo, it's still not "public".

[JoshuaKGoldberg]

Just for visibility, I'm planning on having typescript-eslint take a dependency on the private checker.isTypeAssignableTo API in its next major version (v7): typescript-eslint/typescript-eslint#7936. Hopefully that will give helpful feedback on where to take a future public API later on. Someone should go and yell at us over there if that's a bad idea. 🙂

[jakebailey]

I just merged #56448 which makes isTypeAssignableTo public on the checker for TS 5.4. Check out the PR description and associated links for the justification; the design meeting feedback was all positive. Hard not to be when the external usage has made it load-bearing!

This obviously isn't the entire proposal in the thread (which contains many more relationships and getters), but it is likely the most valuable function given all of the feedback above. It also has the benefit of having been around for a very long time with the same name and behavior, so is a good option for those looking to just "start using it now".

This issue is nowhere near closed, of course. Please do provide feedback for the rest!

[Tofandel]

Is there any way to use isTypeAssignableTo inside a ts file?

I'm looking for a way to check that a type I'm maintaining is assignable to the type of a library (For a unified data model that is extensible)

I simply want typescript to error if my provided type is not assignable to the library type

It seems right now I can do this

const product = null as unknown as ProductCatalog as SfProductCatalogItem; // Error if ProductCatalog and SfProductCatalogItem are not compatible

But it's not typescript only and will polute the output

[jakebailey]

You're effectively asking for #23689/#40468, but you can check this without any runtime emit using extends and a type which only accepts true: Playground Link