never type as argument in conditional sub-type position does not evaluate conditional

[jasonkuhrt]

🔎 Search Terms

never, conditional, parameter, argument

🕗 Version & Regression Information

I did not exhaustively check older versions of TS yet. This issue feels like bug to me, but I don't know how to search for it as its a specific circumstance that has no particular label that I know of.

• This changed between versions ______ and _______
• This changed in commit or PR _______
• This is the behavior in every version I tried, and I reviewed the FAQ for entries about _________
• I was unable to test this on prior versions because _______

⏯ Playground Link

https://www.typescriptlang.org/play/?#code/HYQwtgpgzgDiDGEAE8AWF4GsD6BLK2wEAbhAE7YQAeALhMACYFxngR1lIDeAUAJA0AnjGQASADwwAfEgC8SIqU7U6jKEhhIA-EhpkArsgBcSAGYgANlAg9+QkUnyES5SrXpM5SCQEYZAen8kYJDQhRdldzUkH21dA2MzS2t+QPjDWwFhZCdFVxUPAjzOeQligKDipALoqp09QyQTcysbPjSGmwBfW1BIWARkNAwcJxY2DjdVJmclbjts70kZeU0azzr0xJaUhYdciKnC2fIvMoiK8Ln19U3OpqTW1MqIpHEAWk+v75-fv-+AYCgdotFpMvYcgQfEc1CcSks-Eg0mEQrEbldTvUEg8dm00rieD0eH1oHBECh0Fg8FCYTNxpAOPMsg4JNIvGiop5NFjGs1kjY9pDsNCbnCzuJykighzprdXjztvzno9dsyhSLOVDxYjkSiYtVNfqFTile0gp1Cb02ANycMqWMQKwGflNcKmRClmzVgbZUatianoLHDTRVVShKLlL9ei7ti+U8zRjOB8gam0+m-iCwUGnBrZW7wzqgnro4bYsb4ylExaukA

💻 Code

namespace check_is_never_extends_parameter {
	type $<p> = never extends p ? true : false

	type is_never_extends = $<1> //           never extends 1 ? true : false
	// true

	type is_never_extends_never = $<never> // never extends never ? true : false
	// true
}

namespace check_is_parameter_extends_never {
	type $<p> = p extends never ? true : false

	type is_never_extends_never = $<never> // never extends never ? true : false
	// never <------------------------------------------------------------------ ???

	type is_1_extends_never = $<1> //         1 extends never ? true : false
	// false
}

namespace check_is_1_extends_parameter {
	type $<p> = 1 extends p ? true : false

	type is_1_extends_never = $<never> // 1 extends never ? true : false
	// false

	type is_1_extends_1 = $<1> //         1 extends 1 ? true : false
	// true
}

namespace check_is_parameter_extends_1 {
	type $<p> = p extends 1 ? true : false

	type is_1_extends_never = $<never> // 1 extends never ? true : false
	// never <---------------------------------------------------------- ???

	type is_1_extends_1 = $<1> //         1 extends 1 ? true : false
	// true
}

🙁 Actual behavior

Best way I can describe this so far:

1. never given as a type argument
2. ... to a conditional type
3. ... where the respective parameter is referenced in the sub-type-position of the conditional (x (<-- sub-type position) extends y (<-- super-type position))
4. ... evaluates to never
5. ... instead of the conditional being evaluated (in this case, true/false).

🙂 Expected behavior

I expect a types to be evaluated consistently when never is given as an argument.

Additional information about the issue

I hit this issue while working on my library https://graffle.js.org.

[jasonkuhrt]

I found my answer https://www.zhenghao.io/posts/ts-never#how-to-check-for-never. Related: #23182 (comment)

[MartinJohns]

See also: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types

[jasonkuhrt]

@MartinJohns it appears that "empty union" concept is not explained there. Should it be?

[RyanCavanaugh]

Trying out a FAQ response bot, how would you rate this?

---

TypeScript's conditional types distribute over each member of a union when the type parameter is itself a union. This distribution is typically desirable, but it can sometimes produce surprising results, especially when the type parameter is never (the empty union). For instance, if you write:

// Distributive conditional type

// This type picks Type[] if Type is anything,
// but results in a union if Type is actually a union.
type ToArray<Type> = Type extends any ? Type[] : never;

// Plugging a union into ToArray applies the conditional
// to each member of the union.
type StrArrOrNumArr = ToArray<string | number>;
//   ^ becomes string[] | number[]

In that scenario, passing never (the empty union) effectively yields no members to distribute over, so the resulting type becomes never. For example:

type IsString<T> = T extends string ? "yes" : "no";

// Infers "yes"
type S = IsString<string>;

// Infers "yes" | "no"
type SB = IsString<string | boolean>;

// Distributes over zero members, results in never
type N = IsString<never>;
// never

This explains why some of your code returns never, such as:

namespace check_is_parameter_extends_never {
    type $<p> = p extends never ? true : false;

    // Evaluates to never, because the empty union has no members to distribute over.
    type is_never_extends_never = $<never>;
}

If you need to avoid this distribution—for example, you'd rather treat 'string | number' as a single unit rather than as a union of 'string' and 'number'—you can surround both sides of the extends check with brackets:

// Non-distributive form

type ToArrayNonDist<Type> = [Type] extends [any] ? Type[] : never;

// Now the entire union is taken as a single type,
// producing (string | number)[] instead of string[] | number[]
type ArrOfStrOrNum = ToArrayNonDist<string | number>;
// (string | number)[]

Because never is the empty union, any distributive conditional type that acts on it will result in never. Your examples, such as:

type $<p> = p extends never ? true : false;

type is_never_extends_never = $<never>; // never

are working as intended by the language. If you want a single true/false result in that case, you could wrap the type parameter in brackets, like [p] extends [never]. Otherwise, TypeScript's normal distribution rules mean that p extends never distributes over zero members, leaving you with never as the result.

[MartinJohns]

@MartinJohns it appears that "empty union" concept is not explained there. Should it be?

See also: https://www.typescriptlang.org/docs/handbook/2/functions.html#never

See also: https://github.com/microsoft/typescript/wiki/faq#common-bugs-that-arent-bugs

This conditional type returns never when it should return the true branch.

A good keyword would have been never:

This is the behavior in every version I tried, and I reviewed the FAQ for entries about _________

[jasonkuhrt]

@RyanCavanaugh I would give that 8/10 or something, it's great. I think where it loses some points is that what if we want to support never AND distribution? In that case, it's not possible, and instead we need to change our design actually. So, for that, the FAQ would ideally show alternative patterns. For example in my case I lifted some checks to a layer higher in my type logic that handles never before it calls my utility type that should be using distribution.

Still, this is great, and I wish my AI tools would be as good all the time about TS (I have found that, when working with advanced types, AI basically sucks today. I am using Claude 3.7 Thinking which IIUC is one of the best available on the market 🤷).