Simple type aliases are incosistently resolved

[RunDevelopment]

Search terms

Type alias, resolving types

Expected Behavior

I use some type aliases for documentation, e.g. type Email = string. While TypeScript won't be able to do anything in terms of type checking, these aliases are useful for documenting. As such, I expect that TypeDoc does not resolve these type aliases and displays them as is.

Actual Behavior

TypeDoc sometimes resolves them. This is only the case for aliases of primitive types.

Example:

export type Bar = number;
export type Foo = Bar[];
export class A {
	foo1(a: Bar) { /*...*/ }
	foo2(a: Bar[]) { /*...*/ }
	foo3(a: Set<Bar>) { /*...*/ }
	foo4(a: Foo) { /*...*/ }
}

Screenshots

(Note that Foo is still Bar[].)

Steps to reproduce the bug

Minimal project.

Environment

• Typedoc version: 0.20.23
• TypeScript version: 4.1.3 and 4.2.0-beta
• Node.js version: v14.15.4
• OS: Win10 x64 Version 10.0.19042.746

Additional information

While this is similar to #1472, it is not the same. I was able to confirm that #1472 is fixed when using TS v4.2 but this bug still remained.

The generated doc for the above example code with TS v4.2 and TS v4.1 is exactly the same.

I also want to point out the generated .d.ts declaration files correctly let Bar remain.

export declare type Bar = number;
export declare type Foo = Bar[];
export declare class A {
    foo1(a: Bar): void;
    foo2(a: Bar[]): void;
    foo3(a: Set<Bar>): void;
    foo4(a: Foo): void;
}

I suspect that this has to do with how the TypeScript API is used to resolve the type of symbols. I noticed that VSCode has similar behaviour. It will show the type number for a in foo1 but will show foo(a: Bar): void for foo1 itself.

However, VSCode also shows number[] for Foo, so my suspicion might be wrong.

[Gerrit0]

This is somewhat of an unfixable* bug. This happens because the TypeScript compiler does type interning for primitives for performance reasons. Since 0.20, TypeDoc uses the type checker in the majority of cases in order to retrieve type information, so any type interning will result in us getting the privative type.

We do this because it lets us resolve generic types in classes with a concrete implementation (consider the docs for class MyList extends Array<number>)

You won't see this issue in declaration file emit because that is a purely syntactic transformation - it takes in nodes, and produces other nodes. It never needs to retrieve types.

You can prevent the compiler from interning this type by changing it to an intersection, as if you were making a branded type, but since the property is optional, standard numbers/strings can be used without a type assertion:

type Foo = number & { foo?: never }

See also:

• Should the compiler api resolve certain equivalent types to the first encountered one? microsoft/TypeScript#28197

* Technically we could fix it by always using type nodes and resolving type parameters manually, but this would be horrible...

[RunDevelopment]

While not perfectly equivalent, a branded type works for me. Thank you.