Deprecate If* types in favor of a single If type (#1135)

Author: som-sm

index.d.ts

@@ -143,6 +143,7 @@ export type {And} from './source/and.d.ts';
 export type {Or} from './source/or.d.ts';
 export type {NonEmptyTuple} from './source/non-empty-tuple.d.ts';
 export type {FindGlobalInstanceType, FindGlobalType} from './source/find-global-type.d.ts';
+export type {If} from './source/if.d.ts';
 
 // Template literal types
 export type {CamelCase} from './source/camel-case.d.ts';

readme.md

@@ -211,41 +211,17 @@ Click the type names for complete docs.
 
 ### Type Guard
 
-#### `IsType` vs. `IfType`
-
-For every `IsT` type (e.g. `IsAny`), there is an associated `IfT` type that can help simplify conditional types. While the `IsT` types return a `boolean`, the `IfT` types act like an `If`/`Else` - they resolve to the given `TypeIfT` or `TypeIfNotT` depending on whether `IsX` is `true` or not. By default, `IfT` returns a `boolean`:
-
-```ts
-type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
-	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
-);
-```
-
-#### Usage
-
-```ts
-import type {IsAny, IfAny} from 'type-fest';
-
-type ShouldBeTrue = IsAny<any> extends true ? true : false;
-//=> true
-
-type ShouldBeFalse = IfAny<'not any'>;
-//=> false
-
-type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
-//=> 'never'
-```
-
+- [`If`](source/if.d.ts) - An if-else-like type that resolves depending on whether the given `boolean` type is `true` or `false`.
 - [`IsLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsStringLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsNumericLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsBooleanLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsSymbolLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-- [`IsAny`](source/is-any.d.ts) - Returns a boolean for whether the given type is `any`. (Conditional version: [`IfAny`](source/if-any.d.ts))
-- [`IsNever`](source/is-never.d.ts) - Returns a boolean for whether the given type is `never`. (Conditional version: [`IfNever`](source/if-never.d.ts))
-- [`IsUnknown`](source/is-unknown.d.ts) - Returns a boolean for whether the given type is `unknown`. (Conditional version: [`IfUnknown`](source/if-unknown.d.ts))
-- [`IsEmptyObject`](source/empty-object.d.ts) - Returns a boolean for whether the type is strictly equal to an empty plain object, the `{}` value. (Conditional version: [`IfEmptyObject`](source/if-empty-object.d.ts))
-- [`IsNull`](source/is-null.d.ts) - Returns a boolean for whether the given type is `null`. (Conditional version: [`IfNull`](source/if-null.d.ts))
+- [`IsAny`](source/is-any.d.ts) - Returns a boolean for whether the given type is `any`.
+- [`IsNever`](source/is-never.d.ts) - Returns a boolean for whether the given type is `never`.
+- [`IsUnknown`](source/is-unknown.d.ts) - Returns a boolean for whether the given type is `unknown`.
+- [`IsEmptyObject`](source/empty-object.d.ts) - Returns a boolean for whether the type is strictly equal to an empty plain object, the `{}` value.
+- [`IsNull`](source/is-null.d.ts) - Returns a boolean for whether the given type is `null`.
 - [`IsTuple`](source/is-tuple.d.ts) - Returns a boolean for whether the given array is a tuple.
 
 ### JSON
@@ -375,6 +351,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `SetValues` - See [`IterableElement`](source/iterable-element.d.ts)
 - `PickByTypes` - See [`ConditionalPick`](source/conditional-pick.d.ts)
 - `HomomorphicOmit` - See [`Except`](source/except.d.ts)
+- `IfAny`, `IfNever`, `If*` - See [`If`](source/if.d.ts)
 
 ## Tips
 

source/array-tail.d.ts

@@ -1,4 +1,5 @@
-import type {ApplyDefaultOptions, IfArrayReadonly} from './internal/index.d.ts';
+import type {If} from './if.js';
+import type {ApplyDefaultOptions, IsArrayReadonly} from './internal/index.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
 /**
@@ -63,7 +64,7 @@ export type ArrayTail<TArray extends UnknownArray, Options extends ArrayTailOpti
 		? TArray extends UnknownArray // For distributing `TArray`
 			? _ArrayTail<TArray> extends infer Result
 				? ResolvedOptions['preserveReadonly'] extends true
-					? IfArrayReadonly<TArray, Readonly<Result>, Result>
+					? If<IsArrayReadonly<TArray>, Readonly<Result>, Result>
 					: Result
 				: never // Should never happen
 			: never // Should never happen

source/conditional-keys.d.ts

@@ -1,4 +1,5 @@
-import type {IfNever} from './if-never.d.ts';
+import type {If} from './if.js';
+import type {IsNever} from './is-never.js';
 
 /**
 Extract the keys from a type where the value type of the key extends the given `Condition`.
@@ -40,7 +41,7 @@ export type ConditionalKeys<Base, Condition> =
 	Base[Key] extends Condition
 	// Retain this key
 	// If the value for the key extends never, only include it if `Condition` also extends never
-		? IfNever<Base[Key], IfNever<Condition, Key, never>, Key>
+		? If<IsNever<Base[Key]>, If<IsNever<Condition>, Key, never>, Key>
 	// Discard this key since the condition fails.
 		: never;
 	// Convert the produced object into a union type of the keys which passed the conditional test.

source/if-any.d.ts

@@ -3,6 +3,8 @@ import type {IsAny} from './is-any.d.ts';
 /**
 An if-else-like type that resolves depending on whether the given type is `any`.
 
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
 @see {@link IsAny}
 
 @example

source/if-empty-object.d.ts

@@ -3,6 +3,8 @@ import type {IsEmptyObject} from './empty-object.d.ts';
 /**
 An if-else-like type that resolves depending on whether the given type is `{}`.
 
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
 @see {@link IsEmptyObject}
 
 @example

source/if-never.d.ts

@@ -3,6 +3,8 @@ import type {IsNever} from './is-never.d.ts';
 /**
 An if-else-like type that resolves depending on whether the given type is `never`.
 
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
 @see {@link IsNever}
 
 @example

source/if-null.d.ts

@@ -3,6 +3,8 @@ import type {IsNull} from './is-null.d.ts';
 /**
 An if-else-like type that resolves depending on whether the given type is `null`.
 
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
 @see {@link IsNull}
 
 @example

source/if-unknown.d.ts

@@ -3,6 +3,8 @@ import type {IsUnknown} from './is-unknown.d.ts';
 /**
 An if-else-like type that resolves depending on whether the given type is `unknown`.
 
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
 @see {@link IsUnknown}
 
 @example

source/if.d.ts

@@ -0,0 +1,65 @@
+import type {IsNever} from './is-never.js';
+
+/**
+An if-else-like type that resolves depending on whether the given `boolean` type is `true` or `false`.
+
+Use-cases:
+- You can use this in combination with `Is*` types to create an if-else-like experience. For example, `If<IsAny<any>, 'is any', 'not any'>`.
+
+Note:
+- Returns a union of if branch and else branch if the given type is `boolean` or `any`. For example, `If<boolean, 'Y', 'N'>` will return `'Y' | 'N'`.
+- Returns the else branch if the given type is `never`. For example, `If<never, 'Y', 'N'>` will return `'N'`.
+
+@example
+```
+import {If} from 'type-fest';
+
+type A = If<true, 'yes', 'no'>;
+//=> 'yes'
+
+type B = If<false, 'yes', 'no'>;
+//=> 'no'
+
+type C = If<boolean, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type D = If<any, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type E = If<never, 'yes', 'no'>;
+//=> 'no'
+```
+
+@example
+```
+import {If, IsAny, IsNever} from 'type-fest';
+
+type A = If<IsAny<unknown>, 'is any', 'not any'>;
+//=> 'not any'
+
+type B = If<IsNever<never>, 'is never', 'not never'>;
+//=> 'is never'
+```
+
+@example
+```
+import {If, IsEqual} from 'type-fest';
+
+type IfEqual<T, U, IfBranch, ElseBranch> = If<IsEqual<T, U>, IfBranch, ElseBranch>;
+
+type A = IfEqual<string, string, 'equal', 'not equal'>;
+//=> 'equal'
+
+type B = IfEqual<string, number, 'equal', 'not equal'>;
+//=> 'not equal'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type If<Type extends boolean, IfBranch, ElseBranch> =
+	IsNever<Type> extends true
+		? ElseBranch
+		: Type extends true
+			? IfBranch
+			: ElseBranch;