Add UnionMember 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 {UnionMember} from './source/union-member.d.ts';
 
 // Template literal types
 export type {CamelCase, CamelCaseOptions} from './source/camel-case.d.ts';

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`.
+- [`UnionMember`](source/union-member.d.ts) - Returns a member of a union type. Order is not guaranteed.
 
 ### Type Guard
 
@@ -355,6 +356,8 @@ Click the type names for complete docs.
 - `IfAny`, `IfNever`, `If*` - See [`If`](source/if.d.ts)
 - `MaybePromise` - See [`Promisable`](source/promisable.d.ts)
 - `ReadonlyTuple` - See [`TupleOf`](source/tuple-of.d.ts)
+- `LastOfUnion` - See [`UnionMember`](source/union-member.d.ts)
+- `FirstOfUnion` - See [`UnionMember`](source/union-member.d.ts)
 
 ## Tips
 

source/union-member.d.ts

@@ -0,0 +1,47 @@
+import type {UnionToIntersection} from './union-to-intersection.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Returns a member of a union type. Order is not guaranteed.
+
+Returns `never` when the input is `never`.
+
+@example
+```
+import type {UnionMember} from 'type-fest';
+
+type Last = UnionMember<1 | 2 | 3>;
+//=> 3
+
+type LastNever = UnionMember<never>;
+//=> 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 {UnionMember, IsNever} from 'type-fest';
+
+type UnionToTuple<T, L = UnionMember<T>> =
+	IsNever<T> extends false
+		? [...UnionToTuple<Exclude<T, L>>, L]
+		: [];
+```
+
+@category Type
+*/
+export type UnionMember<T> =
+	IsNever<T> extends true
+		? never
+		: UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+			? R
+			: never;
+
+export {};

source/union-to-tuple.d.ts

@@ -1,19 +1,5 @@
 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 {UnionMember} from './union-member.d.ts';
 
 /**
 Convert a union type into an unordered tuple type of its elements.
@@ -50,7 +36,7 @@ const petList = Object.keys(pets) as UnionToTuple<Pet>;
 
 @category Array
 */
-export type UnionToTuple<T, L = LastOfUnion<T>> =
+export type UnionToTuple<T, L = UnionMember<T>> =
 IsNever<T> extends false
 	? [...UnionToTuple<Exclude<T, L>>, L]
 	: [];

test-d/union-member.ts

@@ -0,0 +1,20 @@
+import {expectType} from 'tsd';
+import type {UnionMember, IsNever} from '../index.d.ts';
+
+// `UnionMember` distinguishes between different modifiers.
+type UnionType = {a: 0} | {b: 0} | {a?: 0} | {readonly a?: 0} | {readonly a: 0};
+expectType<true>({} as UnionMember<UnionType> extends UnionType ? true : false);
+expectType<false>({} as UnionType extends UnionMember<UnionType> ? true : false);
+
+// `never` acts as a termination condition with `IsNever`.
+expectType<never>({} as UnionMember<never>);
+
+expectType<unknown>({} as UnionMember<unknown>);
+expectType<any>({} as UnionMember<any>);
+
+// Ensure exactly one member is selected at a time, while covering all members in the union.
+type UnionToTupleWithExclude<T, L = UnionMember<T>> =
+	IsNever<T> extends false
+		? UnionToTupleWithExclude<Exclude<T, L>> | [L]
+		: never;
+expectType<[1] | [2] | [3]>({} as UnionToTupleWithExclude<1 | 2 | 3>);