Add IsUnion type

index.d.ts

@@ -75,6 +75,7 @@ export type {HasRequiredKeys} from './source/has-required-keys';
 export type {Spread} from './source/spread';
 export type {TupleToUnion} from './source/tuple-to-union';
 export type {IsEqual} from './source/is-equal';
+export type {IsUnion} from './source/is-union';
 
 // Template literal types
 export type {CamelCase} from './source/camel-case';

readme.md

@@ -170,6 +170,7 @@ Click the type names for complete docs.
 - [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
 - [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
 - [`IsEqual`](source/is-equal.d.ts) - Returns a boolean for whether the two given types are equal.
+- [`IsUnion`](source/is-union.d.ts) - Detects whether a given type is a union of types.
 
 ### JSON
 

source/is-union.d.ts

@@ -0,0 +1,24 @@
+import type {UnionToIntersection} from './union-to-intersection';
+
+/**
+Detects whether a given type is a union of types.
+
+While you can default to returning a boolean based on the condition, the resulting typing will be simpler if you instead specify the `True` and `False` type parameters.
+
+Note that `boolean` and `enum` types are unions.
+
+Use-cases:
+- You want to ensure a given type is not a union but a singular type.
+
+@example
+```
+import type {IsUnion} from 'type-fest';
+
+// If `MaybeSingle` is a union type, resolves to `never`, otherwise MaybeSingle.
+type EnsureSingleType<MaybeSingle> = IsUnion<MaybeSingle, never, MaybeSingle>;
+```
+
+@category Utilities
+*/
+export type IsUnion<MaybeUnion, True = true, False = false> =
+  [MaybeUnion] extends [UnionToIntersection<MaybeUnion>] ? False : True;

test-d/is-union.ts

@@ -0,0 +1,28 @@
+import {expectType} from 'tsd';
+import type {IsUnion} from '../index';
+
+declare function isUnion<T>(): IsUnion<T>;
+
+enum Nums {
+	ONE,
+	TWO,
+}
+
+// Non-union types.
+expectType<false>(isUnion<1>());
+expectType<false>(isUnion<number>());
+expectType<false>(isUnion<string>());
+expectType<false>(isUnion<`#${number}`>());
+
+// Unions of self are not unions.
+expectType<false>(isUnion<1 | 1>());
+
+// Union types.
+expectType<true>(isUnion<1 | 2>());
+expectType<true>(isUnion<number | string>());
+expectType<true>(isUnion<'a' | 'b'>());
+expectType<true>(isUnion<Nums.ONE | Nums.TWO>());
+
+// Surprising union types.
+expectType<true>(isUnion<boolean>());
+expectType<true>(isUnion<Nums>());