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

index.d.ts

@@ -167,6 +167,7 @@ export type {IsNullable} from './source/is-nullable.d.ts';
 export type {TupleOf} from './source/tuple-of.d.ts';
 export type {ExclusifyUnion} from './source/exclusify-union.d.ts';
 export type {ArrayReverse} from './source/array-reverse.d.ts';
+export type {LastOfUnion} from './source/last-of-union.d.ts';
 
 // Template literal types
 export type {CamelCase, CamelCaseOptions} from './source/camel-case.d.ts';
@@ -207,5 +208,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

@@ -191,6 +191,7 @@ Click the type names for complete docs.
 - [`ConditionalSimplify`](source/conditional-simplify.d.ts) - Simplifies a type while including and/or excluding certain types from being simplified.
 - [`ConditionalSimplifyDeep`](source/conditional-simplify-deep.d.ts) - Recursively simplifies a type while including and/or excluding certain types from being simplified.
 - [`ExclusifyUnion`](source/exclusify-union.d.ts) - Ensure mutual exclusivity in object unions by adding other members’ keys as `?: never`.
+- [`LastOfUnion`](source/last-of-union.d.ts) - Return a member of a union type. Order is not guaranteed.
 
 ### Type Guard
 
@@ -319,6 +320,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 ensures objects with different key modifiers are not considered identical.
 
 ## Declined types
 

source/exclude-exactly.d.ts

@@ -0,0 +1,124 @@
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {LastOfUnion} from './last-of-union.d.ts';
+
+/**
+Return `never` if the first and second arguments are identical.
+Return the first argument if not.
+(But there's a limitation about union/intersection type. See `IsEqual` in `source/is-equal.d.ts`.)
+
+@example
+```
+type A = MatchOrNever<string | number, string>;
+//=> string | number
+type B = MatchOrNever<string | number, string | number>;
+//=> never
+type C = MatchOrNever<string | number, unknown>;
+//=> string | number
+type D = MatchOrNever<string, string | number>;
+//=> string
+```
+
+This does NOT depend on assignability.
+
+@example
+```
+type RO_0 = MatchOrNever<{readonly a: 0}, {a: 0}>;
+//=> {readonly a: 0}
+type RO_1 = MatchOrNever<{a: 0}, {readonly a: 0}>;
+//=> {a: 0}
+```
+
+`unknown` and `never` cases, which easily break equality in type-level codebase.
+
+@example
+```
+type E = MatchOrNever<unknown, never>;
+//=> unknown
+type F = MatchOrNever<unknown, unknown>;
+//=> never
+type G = MatchOrNever<never, never>;
+//=> never
+type H = MatchOrNever<never, unknown>;
+//=> never
+```
+
+Note that this doesn't regard the identical union/intersection type `T | T` and/or `T & T` as `T` recursively.
+e.g., `{a: 0} | {a: 0}` and/or `{a: 0} & {a: 0}` as `{a: 0}`.
+
+@example
+```
+type IDUnion = MatchOrNever<{a: {b: 0}} | {a: {b: 0}}, {a: {b: 0}}>;
+//=> never
+type A = {a: {b: 0} | {b: 0}};
+type RecurivelyIDUnion = MatchOrNever<A, {a: {b: 0}}>;
+//=> A
+```
+*/
+type MatchOrNever<A, B> =
+	[unknown, B] extends [A, never]
+		? A
+		// This equality code base below doesn't work if `A` is `unknown` and `B` is `never` case.
+		// So this branch should be wrapped to take care of this.
+		: (<G>() => G extends A & G | G ? 1 : 2) extends (<G>() => G extends B & G | G ? 1 : 2)
+			? never
+			: A;
+
+/**
+A stricter version of `Exclude<T, U>` that ensures objects with different key modifiers are not considered identical.
+
+TypeScript's built-in `Exclude` and `ExcludeStrict` in `type-fest` don't distinguish key modifiers of objects.
+
+@example
+```
+import type {ExcludeStrict} from 'type-fest';
+
+type NeverReturned_0 = Exclude<{a: 0} | {readonly a: 0}, {readonly a: 0}>;
+//=> never
+type NeverReturned_1 = ExcludeStrict<{a: 0} | {readonly a: 0}, {readonly a: 0}>;
+//=> never
+```
+
+`ExcludeExactly` keeps the union members element if the members are not identical.
+
+@example
+```
+import type {ExcludeExactly} from 'type-fest';
+
+type ExcludeNever = ExcludeExactly<{a: 0} | {a: 0} | {readonly a: 0}, never>;
+//=> {a: 0} | {a: 0} | {readonly a: 0}
+type ExcludeReadonlyKey = ExcludeExactly<{a: 0} | {readonly a: 0}, {readonly a: 0}>;
+//=> {a: 0}
+type ExcludeKey = ExcludeExactly<{readonly a: 0}, {a: 0}>;
+//=> {readonly a: 0}
+type ExcludeReadonly = ExcludeExactly<{readonly a: 0}, {readonly a: 0}>;
+//=> never
+type ExcludeSubType = ExcludeExactly<0 | 1 | number, 1>;
+//=> number
+type ExcludeAllSet = ExcludeExactly<0 | 1 | number, number>;
+//=> never
+type ExcludeFromUnknown = ExcludeExactly<unknown, string>;
+//=> unknown
+type ExcludeFromUnknownArray = ExcludeExactly<number[] | unknown[], number[]>;
+//=> unknown[]
+```
+
+@category Improved Built-in
+*/
+export type ExcludeExactly<UnionU, DeleteT> =
+	LastOfUnion<DeleteT> extends infer D
+		? true extends IsNever<D>
+			? UnionU
+			: ExcludeExactly<_ExcludeExactly<UnionU, D>, _ExcludeExactly<DeleteT, D>>
+		: never;
+
+type _ExcludeExactly<UnionU, DeleteT> =
+	true extends IsAny<DeleteT>
+		? never
+		: true extends IsUnknown<DeleteT>
+			? never
+			: UnionU extends unknown // Only for union distribution.
+				? MatchOrNever<UnionU, DeleteT>
+				: never;
+export {};

source/last-of-union.d.ts

@@ -0,0 +1,46 @@
+import type {IsNever} from './is-never.d.ts';
+import type {UnionToIntersection} from './union-to-intersection.d.ts';
+
+/**
+Return a member of a union type. Order is not guaranteed.
+Returns `never` when the input is `never`.
+
+@see https://github.com/microsoft/TypeScript/issues/13298#issuecomment-468375328
+
+Use-cases:
+- Implementing recursive type functions that accept a union type.
+- Reducing a union one member at a time, for example when building tuples.
+
+It can detect a termination case using {@link IsNever `IsNever`}.
+
+@example
+```
+import type {LastOfUnion, ExcludeExactly, IsNever} from 'type-fest';
+
+export type UnionToTuple<T, L = LastOfUnion<T>> =
+	IsNever<T> extends false
+		? [...UnionToTuple<ExcludeExactly<T, L>>, L]
+		: [];
+```
+
+@example
+```
+import type {LastOfUnion} from 'type-fest';
+
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+
+type LastNever = LastOfUnion<never>;
+//=> never
+```
+
+@category Type
+*/
+export type LastOfUnion<T> =
+	true extends IsNever<T>
+		? never
+		: UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+			? R
+			: never;
+
+export {};

source/union-to-tuple.d.ts

@@ -1,19 +1,6 @@
 import type {IsNever} from './is-never.d.ts';
-import type {UnionToIntersection} from './union-to-intersection.d.ts';
-
-/**
-Returns the last element of a union type.
-
-@example
-```
-type Last = LastOfUnion<1 | 2 | 3>;
-//=> 3
-```
-*/
-type LastOfUnion<T> =
-UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
-	? R
-	: never;
+import type {ExcludeExactly} from './exclude-exactly.d.ts';
+import type {LastOfUnion} from './last-of-union.d.ts';
 
 /**
 Convert a union type into an unordered tuple type of its elements.
@@ -52,7 +39,9 @@ const petList = Object.keys(pets) as UnionToTuple<Pet>;
 */
 export type UnionToTuple<T, L = LastOfUnion<T>> =
 IsNever<T> extends false
-	? [...UnionToTuple<Exclude<T, L>>, L]
+	? ExcludeExactly<T, L> extends infer E // Improve performance.
+		? [...UnionToTuple<E>, L]
+		: never // Unreachable.
 	: [];
 
 export {};

test-d/exclude-exactly.ts

@@ -0,0 +1,39 @@
+import {expectType} from 'tsd';
+import type {ExcludeExactly} from '../index.d.ts';
+
+expectType<number>({} as ExcludeExactly<0 | 1 | number, '1'>);
+expectType<never>({} as ExcludeExactly<0 | 1 | number, number>);
+expectType<string>({} as ExcludeExactly<'0' | '1' | string, '1'>);
+expectType<never>({} as ExcludeExactly<'0' | '1' | string, string>);
+
+// `{readonly a: t}` should not be equal to `{a: t}` because of assignability.
+expectType<{a: 0}>({} as ExcludeExactly<{a: 0} | {readonly a: 0}, {readonly a: 0}>);
+expectType<{readonly a: 0}>({} as ExcludeExactly<{readonly a: 0}, {a: 0}>);
+expectType<never>({} as ExcludeExactly<{readonly a: 0}, {readonly a: 0}>);
+
+// `never` does nothing.
+expectType<0 | 1 | 2>({} as ExcludeExactly<0 | 1 | 2, never>);
+expectType<never>({} as ExcludeExactly<never, never>);
+
+// `unknown` cannot be excluded like `unknown\T` in any cases.
+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[]>);
+
+// `unknown` and `any` exclude themselves.
+expectType<never>({} as ExcludeExactly<unknown, unknown>);
+expectType<never>({} as ExcludeExactly<unknown, any>);
+expectType<never>({} as ExcludeExactly<any, any>);
+expectType<never>({} as ExcludeExactly<any, unknown>);
+
+// `unknown` and `any` exclude other types.
+expectType<never>({} as ExcludeExactly<string | number, unknown>);
+expectType<never>({} as ExcludeExactly<string | number, any>);
+
+// Union
+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/last-of-union.ts

@@ -0,0 +1,13 @@
+import {expectType} from 'tsd';
+import type {LastOfUnion, IsAny, IsUnknown} from '../index.d.ts';
+
+// `LastOfUnion` distinguishes between different modifiers.
+type UnionType = {a: 0} | {b: 0} | {a?: 0} | {readonly a?: 0} | {readonly a: 0};
+expectType<true>({} as LastOfUnion<UnionType> extends UnionType ? true : false);
+expectType<false>({} as UnionType extends LastOfUnion<UnionType> ? true : false);
+
+// `never` acts as a termination condition with `IsNever`.
+expectType<never>({} as LastOfUnion<never>);
+
+expectType<true>({} as IsUnknown<LastOfUnion<unknown>>);
+expectType<true>({} as IsAny<LastOfUnion<any>>);

test-d/union-to-tuple.ts

@@ -11,3 +11,14 @@ expectType<Options1[number]>({} as (1 | 2 | 3));
 
 type Options2 = UnionToTuple<boolean | 1>;
 expectType<Options2[number]>({} as (1 | false | true));
+
+// Different modifiers cases.
+type DifferentModifiers = {a: 0} | {readonly a: 0} | {a?: 0} | {readonly a?: 0};
+expectType<UnionToTuple<DifferentModifiers>[number]>({} as DifferentModifiers);
+
+// Super type cases.
+type UnionSuperType0 = {a: string; b: string} | {a: string};
+expectType<UnionSuperType0>({} as UnionToTuple<UnionSuperType0>[number]);
+
+type UnionSuperType1 = {a: 1} | {b: 1} | {[x: string]: number};
+expectType<UnionSuperType1>({} as UnionToTuple<UnionSuperType1>[number]);