Add IsNull type

readme.md

@@ -233,10 +233,11 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`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).)
+- [`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))
 
 ### JSON
 

source/if-null.d.ts

@@ -0,0 +1,24 @@
+import type {IsNull} from './is-null';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `null`.
+
+@see {@link IsNull}
+
+@example
+```
+import type {IfNull} from 'type-fest';
+
+type ShouldBeTrue = IfNull<null>;
+//=> true
+
+type ShouldBeBar = IfNull<'not null', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfNull<T, TypeIfNull = true, TypeIfNotNull = false> = (
+ IsNull<T> extends true ? TypeIfNull : TypeIfNotNull
+);

source/internal.d.ts

@@ -429,11 +429,6 @@ Returns a boolean for whether the given `boolean` is not `false`.
 */
 export type IsNotFalse<T extends boolean> = [T] extends [false] ? false : true;
 
-/**
-Returns a boolean for whether the given type is `null`.
-*/
-export type IsNull<T> = [T] extends [null] ? true : false;
-
 /**
 Disallows any of the given keys.
 */

source/is-null.d.ts

@@ -0,0 +1,20 @@
+/**
+Returns a boolean for whether the given type is `null`.
+
+@example
+```
+import type {IsNull} from 'type-fest';
+
+type NonNullFallback<T, Fallback> = IsNull<T> extends true ? Fallback : T;
+
+type Example1 = NonNullFallback<null, string>;
+//=> string
+
+type Example2 = NonNullFallback<number, string>;
+//=? number
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNull<T> = [T] extends [null] ? true : false;

source/is-unknown.d.ts

@@ -1,4 +1,4 @@
-import type {IsNull} from './internal';
+import type {IsNull} from './is-null';
 
 /**
 Returns a boolean for whether the given type is `unknown`.

test-d/internal/is-null.ts → test-d/is-null.ts

@@ -1,5 +1,5 @@
 import {expectType} from 'tsd';
-import type {IsNull} from '../../source/internal';
+import type {IsNull} from '../source/is-null';
 
 // https://www.typescriptlang.org/docs/handbook/type-compatibility.html
 expectType<IsNull<null>>(true);