type-fest 4.16.0 → 4.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.16.0",
+	"version": "4.18.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -39,10 +39,10 @@
 		"generics"
 	],
 	"devDependencies": {
-		"expect-type": "^0.15.0",
+		"expect-type": "^0.19.0",
 		"npm-run-all2": "^6.1.2",
 		"tsd": "^0.31.0",
-		"typescript": "~5.4.3",
+		"typescript": "~5.4.5",
 		"xo": "^0.58.0"
 	},
 	"xo": {

package/readme.md

@@ -151,10 +151,8 @@ Click the type names for complete docs.
 - [`UndefinedOnPartialDeep`](source/undefined-on-partial-deep.d.ts) - Create a deep version of another type where all optional keys are set to also accept `undefined`.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
 - [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
-- [`Tagged`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) if needed.
-- [`UnwrapTagged`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Tagged`.
-- [`Opaque`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d). This implementation only supports a single tag.
-- [`UnwrapOpaque`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Opaque` or `Tagged`.
+- [`Tagged`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) and [per-tag metadata](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf). (This replaces the previous [`Opaque`](source/opaque.d.ts) type, which is now deprecated.)
+- [`UnwrapTagged`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Tagged`. (This replaces the previous [`UnwrapOpaque`](source/opaque.d.ts) type, which is now deprecated.)
 - [`InvariantOf`](source/invariant-of.d.ts) - Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetReadonly`](source/set-readonly.d.ts) - Create a type that makes the given keys readonly.
@@ -200,6 +198,8 @@ Click the type names for complete docs.
 - [`SharedUnionFieldsDeep`](source/shared-union-fields-deep.d.ts) - Create a type with shared fields from a union of object types, deeply traversing nested structures.
 - [`DistributedOmit`](source/distributed-omit.d.ts) - Omits keys from a type, distributing the operation over a union.
 - [`DistributedPick`](source/distributed-pick.d.ts) - Picks keys from a type, distributing the operation over a union.
+- [`And`](source/and.d.ts) - Returns a boolean for whether two given types are both true.
+- [`Or`](source/or.d.ts) - Returns a boolean for whether either of two given types are true.
 
 ### Type Guard
 
@@ -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
 
@@ -344,7 +345,8 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `RequireOnlyOne` - See [`RequireExactlyOne`](source/require-exactly-one.d.ts)
 - `AtMostOne` - See [`RequireOneOrNone`](source/require-one-or-none.d.ts)
 - `AllKeys` - See [`KeysOfUnion`](source/keys-of-union.d.ts)
-- `Branded` - See [`Opaque`](source/opaque.d.ts)
+- `Branded` - See [`Tagged`](source/opaque.d.ts)
+- `Opaque` - See [`Tagged`](source/opaque.d.ts)
 
 ## Tips
 

package/source/and.d.ts

@@ -0,0 +1,25 @@
+import type {IsEqual} from './is-equal';
+
+/**
+Returns a boolean for whether two given types are both true.
+
+Use-case: Constructing complex conditional types where multiple conditions must be satisfied.
+
+@example
+```
+import type {And} from 'type-fest';
+
+And<true, true>;
+//=> true
+
+And<true, false>;
+//=> false
+```
+
+@see {@link Or}
+*/
+export type And<A extends boolean, B extends boolean> = [A, B][number] extends true
+	? true
+	: true extends [IsEqual<A, false>, IsEqual<B, false>][number]
+		? false
+		: never;

package/source/array-slice.d.ts

@@ -3,8 +3,9 @@ import type {LessThanOrEqual} from './less-than-or-equal';
 import type {GreaterThanOrEqual} from './greater-than-or-equal';
 import type {GreaterThan} from './greater-than';
 import type {IsNegative} from './numeric';
-import type {And, Not, ArrayMin} from './internal';
+import type {Not, ArrayMin} from './internal';
 import type {IsEqual} from './is-equal';
+import type {And} from './and';
 import type {ArraySplice} from './array-splice';
 
 /**

package/source/greater-than.d.ts

@@ -1,6 +1,8 @@
-import type {NumberAbsolute, And, Or, PositiveNumericStringGt} from './internal';
+import type {NumberAbsolute, PositiveNumericStringGt} from './internal';
 import type {IsEqual} from './is-equal';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric';
+import type {And} from './and';
+import type {Or} from './or';
 
 /**
 Returns a boolean for whether a given number is greater than another number.

package/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
+);

package/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.
 */
@@ -456,42 +451,6 @@ IsPrimitive<Object>
 */
 export type IsPrimitive<T> = [T] extends [Primitive] ? true : false;
 
-/**
-Returns a boolean for whether A and B are both true.
-
-@example
-```
-And<true, true>;
-//=> true
-
-And<true, false>;
-//=> false
-```
-*/
-export type And<A extends boolean, B extends boolean> = [A, B][number] extends true
-	? true
-	: true extends [IsEqual<A, false>, IsEqual<B, false>][number]
-		? false
-		: never;
-
-/**
-Returns a boolean for either A or B is true.
-
-@example
-```
-Or<true, false>;
-//=> true
-
-Or<false, false>;
-//=> false
-```
-*/
-export type Or<A extends boolean, B extends boolean> = [A, B][number] extends false
-	? false
-	: true extends [IsEqual<A, true>, IsEqual<B, true>][number]
-		? true
-		: never;
-
 /**
 Returns a boolean for whether A is false.
 

package/source/is-never.d.ts

@@ -9,14 +9,7 @@ Useful in type utilities, such as checking if something does not occur.
 
 @example
 ```
-import type {IsNever} from 'type-fest';
-
-type And<A, B> =
-	A extends true
-		? B extends true
-			? true
-			: false
-		: false;
+import type {IsNever, And} from 'type-fest';
 
 // https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
 type AreStringsEqual<A extends string, B extends string> =

package/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;

package/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`.

package/source/numeric.d.ts

@@ -3,7 +3,7 @@ import type {IsInteger} from './is-integer';
 
 export type Numeric = number | bigint;
 
-type Zero = 0 | 0n;
+export type Zero = 0 | 0n;
 
 /**
 Matches the hidden `Infinity` type.

package/source/opaque.d.ts

@@ -76,6 +76,7 @@ type Person = {
 ```
 
 @category Type
+@deprecated Use {@link Tagged} instead
 */
 export type Opaque<Type, Token = unknown> = Type & TagContainer<Token>;
 
@@ -109,6 +110,7 @@ type WillWork = UnwrapOpaque<Tagged<number, 'AccountNumber'>>; // number
 ```
 
 @category Type
+@deprecated Use {@link UnwrapTagged} instead
 */
 export type UnwrapOpaque<OpaqueType extends TagContainer<unknown>> =
 	OpaqueType extends Tag<PropertyKey, any>

package/source/or.d.ts

@@ -0,0 +1,25 @@
+import type {IsEqual} from './is-equal';
+
+/**
+Returns a boolean for whether either of two given types are true.
+
+Use-case: Constructing complex conditional types where multiple conditions must be satisfied.
+
+@example
+```
+import type {Or} from 'type-fest';
+
+Or<true, false>;
+//=> true
+
+Or<false, false>;
+//=> false
+```
+
+@see {@link And}
+*/
+export type Or<A extends boolean, B extends boolean> = [A, B][number] extends false
+	? false
+	: true extends [IsEqual<A, true>, IsEqual<B, true>][number]
+		? true
+		: never;

package/source/subtract.d.ts

@@ -1,8 +1,10 @@
-import type {NumberAbsolute, BuildTuple, And, Or} from './internal';
+import type {NumberAbsolute, BuildTuple} from './internal';
 import type {IsEqual} from './is-equal';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric';
 import type {LessThan} from './less-than';
 import type {Sum} from './sum';
+import type {And} from './and';
+import type {Or} from './or';
 
 /**
 Returns the difference between two numbers.

package/source/sum.d.ts

@@ -1,7 +1,9 @@
-import type {NumberAbsolute, BuildTuple, And, Or, ArrayMax, ArrayMin} from './internal';
+import type {NumberAbsolute, BuildTuple, ArrayMax, ArrayMin} from './internal';
 import type {IsEqual} from './is-equal';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric';
 import type {Subtract} from './subtract';
+import type {And} from './and';
+import type {Or} from './or';
 
 /**
 Returns the sum of two numbers.

package/source/tsconfig-json.d.ts

@@ -19,6 +19,7 @@ declare namespace TsConfigJson {
 			| 'ESNext'
 			| 'Node16'
 			| 'NodeNext'
+			| 'Preserve'
 			| 'None'
 			// Lowercase alternatives
 			| 'commonjs'
@@ -32,6 +33,7 @@ declare namespace TsConfigJson {
 			| 'esnext'
 			| 'node16'
 			| 'nodenext'
+			| 'preserve'
 			| 'none';
 
 		export type NewLine =
@@ -113,6 +115,14 @@ declare namespace TsConfigJson {
 			| 'ES2021.Promise'
 			| 'ES2021.String'
 			| 'ES2021.WeakRef'
+			| 'ES2022'
+			| 'ES2022.Array'
+			| 'ES2022.Error'
+			| 'ES2022.Intl'
+			| 'ES2022.Object'
+			| 'ES2022.SharedMemory'
+			| 'ES2022.String'
+			| 'ES2022.RegExp'
 			| 'ESNext'
 			| 'ESNext.Array'
 			| 'ESNext.AsyncIterable'
@@ -172,6 +182,14 @@ declare namespace TsConfigJson {
 			| 'es2021.promise'
 			| 'es2021.string'
 			| 'es2021.weakref'
+			| 'es2022'
+			| 'es2022.array'
+			| 'es2022.error'
+			| 'es2022.intl'
+			| 'es2022.object'
+			| 'es2022.sharedmemory'
+			| 'es2022.string'
+			| 'es2022.regexp'
 			| 'esnext'
 			| 'esnext.array'
 			| 'esnext.asynciterable'