UnionToTuple: Fix behavior when a union member is a supertype of another; Add ExcludeExactly type (#1349)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
Co-authored-by: Som Shekhar Mukherjee <iamssmkhrj@gmail.com>

Author: 3 people

index.d.ts

@@ -213,5 +213,6 @@ export type {TsConfigJson} from './source/tsconfig-json.d.ts';
 export type {ExtendsStrict} from './source/extends-strict.d.ts';
 export type {ExtractStrict} from './source/extract-strict.d.ts';
 export type {ExcludeStrict} from './source/exclude-strict.d.ts';
+export type {ExcludeExactly} from './source/exclude-exactly.d.ts';
 
 export {};

readme.md

@@ -325,6 +325,7 @@ Click the type names for complete docs.
 - [`ExtendsStrict`](source/extends-strict.d.ts) - A stricter, non-distributive version of `extends` for checking whether one type is assignable to another.
 - [`ExtractStrict`](source/extract-strict.d.ts) - A stricter version of `Extract<T, U>` that ensures every member of `U` can successfully extract something from `T`.
 - [`ExcludeStrict`](source/exclude-strict.d.ts) - A stricter version of `Exclude<T, U>` that ensures every member of `U` can successfully exclude something from `T`.
+- [`ExcludeExactly`](source/exclude-exactly.d.ts) - A stricter version of `Exclude<T, U>` that excludes types only when they are exactly identical.
 
 ## Declined types
 

source/exclude-exactly.d.ts

@@ -0,0 +1,57 @@
+import type {IsNever} from './is-never.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {If} from './if.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+A stricter version of `Exclude<T, U>` that excludes types only when they are exactly identical.
+
+@example
+```
+import type {ExcludeExactly} from 'type-fest';
+
+type TestExclude1 = Exclude<'a' | 'b' | 'c' | 1 | 2 | 3, string>;
+//=> 1 | 2 | 3
+
+type TestExcludeExactly1 = ExcludeExactly<'a' | 'b' | 'c' | 1 | 2 | 3, string>;
+//=> 'a' | 'b' | 'c' | 1 | 2 | 3
+
+type TestExclude2 = Exclude<'a' | 'b' | 'c' | 1 | 2 | 3, any>;
+//=> never
+
+type TestExcludeExactly2 = ExcludeExactly<'a' | 'b' | 'c' | 1 | 2 | 3, any>;
+//=> 'a' | 'b' | 'c' | 1 | 2 | 3
+
+type TestExclude3 = Exclude<{a: string} | {a: string; b: string}, {a: string}>;
+//=> never
+
+type TestExcludeExactly3 = ExcludeExactly<{a: string} | {a: string; b: string}, {a: string}>;
+//=> {a: string; b: string}
+```
+
+@category Improved Built-in
+*/
+export type ExcludeExactly<Union, Delete> =
+	IfNotAnyOrNever<
+		Union,
+		_ExcludeExactly<Union, Delete>,
+		// If `Union` is `any`, then if `Delete` is `any`, return `never`, else return `Union`.
+		If<IsAny<Delete>, never, Union>,
+		// If `Union` is `never`, then if `Delete` is `never`, return `never`, else return `Union`.
+		If<IsNever<Delete>, never, Union>
+	>;
+
+type _ExcludeExactly<Union, Delete> =
+	IfNotAnyOrNever<Delete,
+		Union extends unknown // For distributing `Union`
+			? [Delete extends unknown // For distributing `Delete`
+				? If<IsEqual<Union, Delete>, true, never>
+				: never] extends [never] ? Union : never
+			: never,
+		// If `Delete` is `any` or `never`, then return `Union`,
+		// because `Union` cannot be `any` or `never` here.
+		Union, Union
+	>;
+
+export {};

source/internal/type.d.ts

@@ -3,6 +3,7 @@ import type {IsAny} from '../is-any.d.ts';
 import type {IsNever} from '../is-never.d.ts';
 import type {Primitive} from '../primitive.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
+import type {UnionToIntersection} from '../union-to-intersection.d.ts';
 
 /**
 Matches any primitive, `void`, `Date`, or `RegExp` value.

source/is-equal.d.ts

@@ -1,4 +1,3 @@
-import type {IsNever} from './is-never.d.ts';
 /**
 Returns a boolean for whether the two given types are equal.
 

source/union-to-tuple.d.ts

@@ -1,3 +1,4 @@
+import type {ExcludeExactly} from './exclude-exactly.d.ts';
 import type {IsNever} from './is-never.d.ts';
 import type {UnionMember} from './union-member.d.ts';
 
@@ -38,7 +39,7 @@ const petList = Object.keys(pets) as UnionToTuple<Pet>;
 */
 export type UnionToTuple<T, L = UnionMember<T>> =
 IsNever<T> extends false
-	? [...UnionToTuple<Exclude<T, L>>, L]
+	? [...UnionToTuple<ExcludeExactly<T, L>>, L]
 	: [];
 
 export {};

test-d/exclude-exactly.ts

@@ -0,0 +1,51 @@
+import {expectType} from 'tsd';
+import type {ExcludeExactly} from '../index.d.ts';
+
+expectType<number>({} as ExcludeExactly<number, '1'>);
+expectType<never>({} as ExcludeExactly<number, number>);
+expectType<0>({} as ExcludeExactly<0, number>);
+expectType<string>({} as ExcludeExactly<string, '1'>);
+expectType<never>({} as ExcludeExactly<string, string>);
+expectType<'0'>({} as ExcludeExactly<'0', string>);
+
+expectType<{a: 0}>({} as ExcludeExactly<{a: 0} | {readonly a: 0}, {readonly a: 0}>);
+expectType<{readonly a: 0}>({} as ExcludeExactly<{a: 0} | {readonly a: 0}, {a: 0}>);
+expectType<never>({} as ExcludeExactly<{readonly a: 0}, {readonly a: 0}>);
+
+// `never` excludes nothing
+expectType<0 | 1 | 2>({} as ExcludeExactly<0 | 1 | 2, never>);
+expectType<never>({} as ExcludeExactly<never, never>);
+expectType<any>({} as ExcludeExactly<any, never>);
+expectType<unknown>({} as ExcludeExactly<unknown, never>);
+
+// Excluding from `unknown`/`any`
+expectType<unknown>({} as ExcludeExactly<unknown, string>);
+expectType<[unknown]>({} as ExcludeExactly<[unknown], [number]>);
+expectType<unknown[]>({} as ExcludeExactly<unknown[], number[]>);
+expectType<{a: unknown}>({} as ExcludeExactly<{a: unknown}, {a: number}>);
+expectType<unknown[]>({} as ExcludeExactly<number[] | unknown[], number[]>);
+expectType<any>({} as ExcludeExactly<any, string>);
+expectType<[any]>({} as ExcludeExactly<[any], [number]>);
+expectType<any[]>({} as ExcludeExactly<any[], number[]>);
+expectType<{a: any}>({} as ExcludeExactly<{a: any}, {a: number}>);
+expectType<any[]>({} as ExcludeExactly<number[] | any[], number[]>);
+
+// Excluding `unknown`/`any`
+expectType<never>({} as ExcludeExactly<unknown, unknown>);
+expectType<never>({} as ExcludeExactly<any, any>);
+expectType<unknown>({} as ExcludeExactly<unknown, any>);
+expectType<any>({} as ExcludeExactly<any, unknown>);
+expectType<string | number>({} as ExcludeExactly<string | number, unknown>);
+expectType<string | number>({} as ExcludeExactly<string | number, any>);
+expectType<never>({} as ExcludeExactly<never, any>);
+expectType<never>({} as ExcludeExactly<never, unknown>);
+
+// Unions
+expectType<2>({} as ExcludeExactly<0 | 1 | 2, 0 | 1>);
+expectType<never>({} as ExcludeExactly<0 | 1 | 2, 0 | 1 | 2>);
+expectType<{readonly a?: 0}>({} as ExcludeExactly<
+	{a: 0} | {readonly a: 0} | {a?: 0} | {readonly a?: 0}, {a: 0} | {readonly a: 0} | {a?: 0}
+>);
+expectType<never>({} as ExcludeExactly<
+	{a: 0} | {readonly a: 0} | {a?: 0} | {readonly a?: 0}, {a: 0} | {readonly a: 0} | {a?: 0} | {readonly a?: 0}
+>);

test-d/union-to-tuple.ts

@@ -11,3 +11,15 @@ expectType<Options1[number]>({} as (1 | 2 | 3));
 
 type Options2 = UnionToTuple<boolean | 1>;
 expectType<Options2[number]>({} as (1 | false | true));
+
+// Test for https://github.com/sindresorhus/type-fest/issues/1352
+// This union is special because `{readonly a: 0}` extends `{a: 0}`, and `{a: 0}` also extends `{readonly a: 0}`,
+// meaning both types are assignable to each other.
+// See [this comment](https://github.com/sindresorhus/type-fest/pull/1349#issuecomment-3858719735) for more details.
+type DifferentModifierUnion = {readonly a: 0} | {a: 0};
+expectType<DifferentModifierUnion>({} as UnionToTuple<DifferentModifierUnion>[number]);
+
+// Edge cases.
+expectType<[]>({} as UnionToTuple<never>);
+expectType<[any]>({} as UnionToTuple<any>);
+expectType<[unknown]>({} as UnionToTuple<unknown>);