type-fest 5.4.3 → 5.5.0

package/source/merge.d.ts

@@ -12,6 +12,31 @@ type SimpleMerge<Destination, Source> = Simplify<{
 /**
 Merge two types into a new type. Keys of the second type overrides keys of the first type.
 
+This is different from the TypeScript `&` (intersection) operator. With `&`, conflicting property types are intersected, which often results in `never`. For example, `{a: string} & {a: number}` makes `a` become `string & number`, which resolves to `never`. With `Merge`, the second type's keys cleanly override the first, so `Merge<{a: string}, {a: number}>` gives `{a: number}` as expected. `Merge` also produces a flattened type (via `Simplify`), making it more readable in IDE tooltips compared to `A & B`.
+
+@example
+```
+import type {Merge} from 'type-fest';
+
+type Foo = {
+	a: string;
+	b: number;
+};
+
+type Bar = {
+	a: number; // Conflicts with Foo['a']
+	c: boolean;
+};
+
+// With `&`, `a` becomes `string & number` which is `never`. Not what you want.
+type WithIntersection = (Foo & Bar)['a'];
+//=> never
+
+// With `Merge`, `a` is cleanly overridden to `number`.
+type WithMerge = Merge<Foo, Bar>['a'];
+//=> number
+```
+
 @example
 ```
 import type {Merge} from 'type-fest';

package/source/omit-deep.d.ts

@@ -5,7 +5,6 @@ import type {IsNever} from './is-never.d.ts';
 import type {LiteralUnion} from './literal-union.d.ts';
 import type {Paths} from './paths.d.ts';
 import type {SimplifyDeep} from './simplify-deep.d.ts';
-import type {Simplify} from './simplify.d.ts';
 import type {UnionToTuple} from './union-to-tuple.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
@@ -119,7 +118,7 @@ P extends `${infer RecordKeyInPath}.${infer SubPath}`
 		? IsNever<Key> extends true
 			? ObjectT
 			: Key extends PropertyKey
-				? Simplify<Omit<ObjectT, Key>> // `Simplify` to prevent `Omit` from appearing in the resulting type
+				? Omit<ObjectT, Key>
 				: ObjectT
 		: ObjectT;
 

package/source/optional.d.ts

@@ -0,0 +1,31 @@
+/**
+Create a type that represents either the value or `undefined`, while stripping `null` from the type.
+
+Use-cases:
+- Enforcing the practice of using `undefined` instead of `null` as the "absence of value" marker.
+- Converting APIs that return `null` (DOM, JSON, legacy libraries) to use `undefined` consistently.
+
+@example
+```
+import type {Optional} from 'type-fest';
+
+// Adds `undefined` to the type
+type MaybeNumber = Optional<number>;
+//=> number | undefined
+
+// Strips `null` from the type
+type NullableString = Optional<string | null>;
+//=> string | undefined
+
+type Config = {
+	name: string;
+	description: Optional<string>;
+	//=> string | undefined
+};
+```
+
+@category Utilities
+*/
+export type Optional<Value> = Exclude<Value, null> | undefined;
+
+export {};

package/source/or-all.d.ts

@@ -0,0 +1,73 @@
+import type {SomeExtend} from './some-extend.d.ts';
+
+/**
+Returns a boolean for whether any of the given elements is `true`.
+
+Use-cases:
+- Check if at least one condition in a list of booleans is met.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type FFT = OrAll<[false, false, true]>;
+//=> true
+
+type FFF = OrAll<[false, false, false]>;
+//=> false
+```
+
+Note: When `boolean` is passed as an element, it is distributed into separate cases, and the final result is a union of those cases.
+For example, `OrAll<[false, boolean]>` expands to `OrAll<[false, true]> | OrAll<[false, false]>`, which simplifies to `true | false` (i.e., `boolean`).
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[false, boolean]>;
+//=> boolean
+
+type B = OrAll<[true, boolean]>;
+//=> true
+```
+
+Note: If `never` is passed as an element, it is treated as `false` and the result is computed accordingly.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[never, never, true]>;
+//=> true
+
+type B = OrAll<[never, never, false]>;
+//=> false
+
+type C = OrAll<[never, never, never]>;
+//=> false
+
+type D = OrAll<[never, never, boolean]>;
+//=> boolean
+```
+
+Note: If `any` is passed as an element, it is treated as `boolean` and the result is computed accordingly.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[false, any]>;
+//=> boolean
+
+type B = OrAll<[true, any]>;
+//=> true
+```
+
+Note: `OrAll<[]>` evaluates to `false` because there are no `true` elements in an empty tuple. See [Wikipedia: Clause (logic) > Empty clauses](https://en.wikipedia.org/wiki/Clause_(logic)#Empty_clauses:~:text=The%20truth%20evaluation%20of%20an%20empty%20disjunctive%20clause%20is%20always%20false.).
+
+@see {@link Or}
+@see {@link AndAll}
+*/
+export type OrAll<T extends readonly boolean[]> = SomeExtend<T, true>;
+
+export {};

package/source/or.d.ts

@@ -1,5 +1,4 @@
-import type {If} from './if.d.ts';
-import type {IsNever} from './is-never.d.ts';
+import type {OrAll} from './or-all.d.ts';
 
 /**
 Returns a boolean for whether either of two given types is true.
@@ -74,16 +73,10 @@ type G = Or<never, never>;
 //=> false
 ```
 
+@see {@link OrAll}
 @see {@link And}
 @see {@link Xor}
 */
-export type Or<A extends boolean, B extends boolean> =
-	_Or<If<IsNever<A>, false, A>, If<IsNever<B>, false, B>>; // `never` is treated as `false`
-
-export type _Or<A extends boolean, B extends boolean> = A extends true
-	? true
-	: B extends true
-		? true
-		: false;
+export type Or<A extends boolean, B extends boolean> = OrAll<[A, B]>;
 
 export {};

package/source/package-json.d.ts

@@ -1,5 +1,5 @@
-import type {LiteralUnion} from './literal-union.d.ts';
 import type {JsonObject, JsonValue} from './json-value.d.ts';
+import type {LiteralUnion} from './literal-union.d.ts';
 
 export namespace PackageJson {
 	/**
@@ -526,7 +526,7 @@ export namespace PackageJson {
 		Engines that this package runs on.
 		*/
 		engines?: {
-			[EngineName in 'npm' | 'node' | string]?: string;
+			[EngineName in LiteralUnion<'npm' | 'node', string>]?: string;
 		};
 
 		/**

package/source/paths.d.ts

@@ -1,4 +1,4 @@
-import type {StaticPartOfArray, VariablePartOfArray, NonRecursiveType, ToString, IsNumberLike, ApplyDefaultOptions} from './internal/index.d.ts';
+import type {NonRecursiveType, ToString, IsNumberLike, ApplyDefaultOptions, MapsSetsOrArrays} from './internal/index.d.ts';
 import type {IsAny} from './is-any.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 import type {GreaterThan} from './greater-than.d.ts';
@@ -192,67 +192,50 @@ open('listB.1'); // TypeError. Because listB only has one element.
 export type Paths<T, Options extends PathsOptions = {}> = _Paths<T, ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, Options>>;
 
 type _Paths<T, Options extends Required<PathsOptions>, CurrentDepth extends number = 0> =
-	T extends NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
+	T extends NonRecursiveType | Exclude<MapsSetsOrArrays, UnknownArray>
 		? never
 		: IsAny<T> extends true
 			? never
-			: T extends UnknownArray
-				? number extends T['length']
-					// We need to handle the fixed and non-fixed index part of the array separately.
-					? InternalPaths<StaticPartOfArray<T>, Options, CurrentDepth> | InternalPaths<Array<VariablePartOfArray<T>[number]>, Options, CurrentDepth>
-					: InternalPaths<T, Options, CurrentDepth>
-				: T extends object
-					? InternalPaths<T, Options, CurrentDepth>
-					: never;
+			: T extends object
+				? InternalPaths<Required<T>, Options, CurrentDepth>
+				: never;
 
 type InternalPaths<T, Options extends Required<PathsOptions>, CurrentDepth extends number> =
-	Options['maxRecursionDepth'] extends infer MaxDepth extends number
-		? Required<T> extends infer T
-			? T extends readonly []
-				? never
-				: IsNever<keyof T> extends true // Check for empty object
-					? never
-					: {
-						[Key in keyof T]:
-						Key extends string | number // Limit `Key` to string or number.
-							? (
-								And<Options['bracketNotation'], IsNumberLike<Key>> extends true
-									? `[${Key}]`
-									// If `Key` is a number, return `Key | `${Key}``, because both `array[0]` and `array['0']` work.
-									: CurrentDepth extends 0
-										? Key | ToString<Key>
-										: `.${(Key | ToString<Key>)}`
-							) extends infer TranformedKey extends string | number ?
-							// 1. If style is 'a[0].b' and 'Key' is a numberlike value like 3 or '3', transform 'Key' to `[${Key}]`, else to `${Key}` | Key
-							// 2. If style is 'a.0.b', transform 'Key' to `${Key}` | Key
-							| ((Options['leavesOnly'] extends true
-								? MaxDepth extends CurrentDepth
-									? TranformedKey
-									: T[Key] extends infer Value
-										? (Value extends readonly [] | NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
-											? TranformedKey
-											: IsNever<keyof Value> extends true // Check for empty object
-												? TranformedKey
-												: never)
-										: never
-								: TranformedKey
-							) extends infer _TransformedKey
-								// If `depth` is provided, the condition becomes truthy only when it reaches `CurrentDepth`.
-								// Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths.
-								? CurrentDepth extends Options['depth']
-									? _TransformedKey
-									: never
-								: never)
-							| (
-								// Recursively generate paths for the current key
-								GreaterThan<MaxDepth, CurrentDepth> extends true // Limit the depth to prevent infinite recursion
-									? `${TranformedKey}${_Paths<T[Key], Options, Sum<CurrentDepth, 1>> & (string | number)}`
-									: never
-							)
-								: never
-							: never
-					}[keyof T & (T extends UnknownArray ? number : unknown)]
+	{[Key in keyof T]: Key extends string | number // Limit `Key` to `string | number`
+		? (
+			And<Options['bracketNotation'], IsNumberLike<Key>> extends true
+				? `[${Key}]`
+				: CurrentDepth extends 0
+					// Return both `Key` and `ToString<Key>` because for number keys, like `1`, both `1` and `'1'` are valid keys.
+					? Key | ToString<Key>
+					: `.${(Key | ToString<Key>)}`
+		) extends infer TransformedKey extends string | number
+			? ((Options['leavesOnly'] extends true
+				? Options['maxRecursionDepth'] extends CurrentDepth
+					? TransformedKey
+					: IsNever<T[Key]> extends true
+						? TransformedKey
+						: T[Key] extends infer Value // For distributing `T[Key]`
+							? (Value extends readonly [] | NonRecursiveType | Exclude<MapsSetsOrArrays, UnknownArray>
+								? TransformedKey
+								: IsNever<keyof Value> extends true // Check for empty object & `unknown`, because `keyof unknown` is `never`.
+									? TransformedKey
+									: never)
+							: never // Should never happen
+				: TransformedKey
+			) extends infer _TransformedKey
+				// If `depth` is provided, the condition becomes truthy only when it matches `CurrentDepth`.
+				// Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths.
+				? CurrentDepth extends Options['depth']
+					? _TransformedKey
+					: never
+				: never)
+			// Recursively generate paths for the current key
+			| (GreaterThan<Options['maxRecursionDepth'], CurrentDepth> extends true // Limit the depth to prevent infinite recursion
+				? `${TransformedKey}${_Paths<T[Key], Options, Sum<CurrentDepth, 1>> & (string | number)}`
+				: never)
 			: never
-		: never;
+		: never
+	}[keyof T & (T extends UnknownArray ? number : unknown)];
 
 export {};

package/source/pick-deep.d.ts

@@ -5,6 +5,7 @@ import type {Paths} from './paths.d.ts';
 import type {Simplify} from './simplify.d.ts';
 import type {UnionToIntersection} from './union-to-intersection.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
+import type {SimplifyDeep} from './simplify-deep.d.ts';
 
 /**
 Pick properties from a deeply-nested object.
@@ -36,24 +37,15 @@ type Configuration = {
 };
 
 type NameConfig = PickDeep<Configuration, 'userConfig.name'>;
-// type NameConfig = {
-// 	userConfig: {
-// 		name: string;
-// 	}
-// };
+//=> {userConfig: {name: string}}
 
 // Supports optional properties
 type User = PickDeep<PartialDeep<Configuration>, 'userConfig.name' | 'userConfig.age'>;
-// type User = {
-// 	userConfig?: {
-// 		name?: string;
-// 		age?: number;
-// 	};
-// };
+//=> {userConfig?: {name?: string; age?: number}}
 
 // Supports array
 type AddressConfig = PickDeep<Configuration, 'userConfig.address.0'>;
-// type AddressConfig = {
+//=> {
 // 	userConfig: {
 // 		address: [{
 // 			city1: string;
@@ -64,14 +56,7 @@ type AddressConfig = PickDeep<Configuration, 'userConfig.address.0'>;
 
 // Supports recurse into array
 type Street = PickDeep<Configuration, 'userConfig.address.1.street2'>;
-// type Street = {
-// 	userConfig: {
-// 		address: [
-// 			unknown,
-// 			{street2: string}
-// 		];
-// 	};
-// }
+//=> {userConfig: {address: [unknown, {street2: string}]}}
 ```
 
 @category Object
@@ -86,7 +71,7 @@ export type PickDeep<T, PathUnion extends Paths<T>> =
 			}[PathUnion]
 			>
 			: T extends object
-				? Simplify<UnionToIntersection<{
+				? SimplifyDeep<UnionToIntersection<{
 					[P in PathUnion]: InternalPickDeep<T, P>;
 				}[PathUnion]>>
 				: never;

package/source/set-non-nullable.d.ts

@@ -15,19 +15,12 @@ type Foo = {
 	c?: boolean | null;
 };
 
+// Note: In the following example, `c` can no longer be `null`, but it's still optional.
 type SomeNonNullable = SetNonNullable<Foo, 'b' | 'c'>;
-// type SomeNonNullable = {
-// 	a: number | null;
-// 	b: string; // Can no longer be undefined.
-// 	c?: boolean; // Can no longer be null, but is still optional.
-// }
+//=> {a: null | number; b: string; c?: boolean}
 
 type AllNonNullable = SetNonNullable<Foo>;
-// type AllNonNullable = {
-// 	a: number; // Can no longer be null.
-// 	b: string; // Can no longer be undefined.
-// 	c?: boolean; // Can no longer be null, but is still optional.
-// }
+//=> {a: number; b: string; c?: boolean}
 ```
 
 @category Object

package/source/set-optional.d.ts

@@ -18,11 +18,7 @@ type Foo = {
 };
 
 type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
-// type SomeOptional = {
-// 	a: number;
-// 	b?: string; // Was already optional and still is.
-// 	c?: boolean; // Is now optional.
-// }
+//=> {a: number; b?: string; c?: boolean}
 ```
 
 @category Object

package/source/set-parameter-type.d.ts

@@ -38,14 +38,14 @@ type MergeObjectToArray<TArray extends UnknownArray, TObject, TArrayCopy extends
 					: K extends keyof TObject ? TObject[K] : TArray[K]
 			}
 		: TObject extends object
-			// If `TObject` is a object witch key is number like `{0: string, 1: number}`
+			// If `TObject` is an object with number keys like `{0: string, 1: number}`
 			? {
 				[K in keyof TArray]:
 				K extends `${infer NumberK extends number}`
 					? NumberK extends keyof TObject ? TObject[NumberK] : TArray[K]
 					: number extends K
 					// If array key `K` is `number`, means it's a rest parameter, we should set the rest parameter type to corresponding type in `TObject`.
-					// example: `MergeObjectToParamterArray<[string, ...boolean[]], {1: number}>` => `[string, ...number[]]`
+					// example: `MergeObjectToArray<[string, ...boolean[]], {1: number}>` => `[string, ...number[]]`
 						? StaticPartOfArray<TArrayCopy>['length'] extends keyof TObject
 							? TObject[StaticPartOfArray<TArrayCopy>['length']]
 							: TArray[K]

package/source/set-readonly.d.ts

@@ -18,11 +18,7 @@ type Foo = {
 };
 
 type SomeReadonly = SetReadonly<Foo, 'b' | 'c'>;
-// type SomeReadonly = {
-// 	a: number;
-// 	readonly b: string; // Was already readonly and still is.
-// 	readonly c: boolean; // Is now readonly.
-// }
+//=> {a: number; readonly b: string; readonly c: boolean}
 ```
 
 @category Object

package/source/set-required.d.ts

@@ -21,11 +21,7 @@ type Foo = {
 };
 
 type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
-// type SomeRequired = {
-// 	a?: number;
-// 	b: string; // Was already required and still is.
-// 	c: boolean; // Is now required.
-// }
+//=> {a?: number; b: string; c: boolean}
 
 // Set specific indices in an array to be required.
 type ArrayExample = SetRequired<[number?, number?, number?], 0 | 1>;

package/source/shared-union-fields-deep.d.ts

@@ -89,7 +89,7 @@ function displayPetInfoWithSharedUnionFieldsDeep(petInfo: SharedUnionFieldsDeep<
 export type SharedUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOptions = {}> =
 	ApplyDefaultOptions<SharedUnionFieldsDeepOptions, DefaultSharedUnionFieldsDeepOptions, Options> extends infer OptionsWithDefaults extends Required<SharedUnionFieldsDeepOptions>
 	// `Union extends` will convert `Union`
-	// to a [distributive conditionaltype](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+	// to a [distributive conditional type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
 	// But this is not what we want, so we need to wrap `Union` with `[]` to prevent it.
 		? [Union] extends [NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>]
 			? Union

package/source/some-extend.d.ts

@@ -0,0 +1,113 @@
+import type {CollapseRestElement} from './internal/array.d.ts';
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {IfNotAnyOrNever, Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Or} from './or.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+@see {@link SomeExtend}
+*/
+export type SomeExtendOptions = {
+	/**
+	Consider `never` elements to match the target type only if the target type itself is `never` (or `any`).
+
+	- When set to `true` (default), `never` is _not_ treated as a bottom type, instead, it is treated as a type that matches only itself (or `any`).
+	- When set to `false`, `never` is treated as a bottom type, and behaves as it normally would.
+
+	@default true
+
+	@example
+	```
+	import type {SomeExtend} from 'type-fest';
+
+	type A = SomeExtend<[1, 2, never], string, {strictNever: true}>;
+	//=> false
+
+	type B = SomeExtend<[1, 2, never], string, {strictNever: false}>;
+	//=> true
+
+	type C = SomeExtend<[1, never], never, {strictNever: true}>;
+	//=> true
+
+	type D = SomeExtend<[1, never], never, {strictNever: false}>;
+	//=> true
+
+	type E = SomeExtend<[never], any, {strictNever: true}>;
+	//=> true
+
+	type F = SomeExtend<[never], any, {strictNever: false}>;
+	//=> true
+	```
+	*/
+	strictNever?: boolean;
+};
+
+type DefaultSomeExtendOptions = {
+	strictNever: true;
+};
+
+/**
+Returns a boolean for whether some element in an array type extends another type.
+
+@example
+```
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<['1', '2', 3], number>;
+//=> true
+
+type B = SomeExtend<[1, 2, 3], string>;
+//=> false
+
+type C = SomeExtend<[string, number | string], number>;
+//=> boolean
+
+type D = SomeExtend<[true, boolean, true], false>;
+//=> boolean
+```
+
+Note: Behaviour of optional elements depend on the `exactOptionalPropertyTypes` compiler option. When the option is disabled, the target type must include `undefined` for a successful match.
+
+```
+// @exactOptionalPropertyTypes: true
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<[1?, 2?, '3'?], string>;
+//=> true
+```
+
+```
+// @exactOptionalPropertyTypes: false
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<[1?, 2?, '3'?], string>;
+//=> boolean
+
+type B = SomeExtend<[1?, 2?, '3'?], string | undefined>;
+//=> true
+```
+
+@see {@link SomeExtendOptions}
+
+@category Utilities
+@category Array
+*/
+export type SomeExtend<TArray extends UnknownArray, Type, Options extends SomeExtendOptions = {}> =
+	_SomeExtend<CollapseRestElement<TArray>, Type, ApplyDefaultOptions<SomeExtendOptions, DefaultSomeExtendOptions, Options>>;
+
+type _SomeExtend<TArray extends UnknownArray, Type, Options extends Required<SomeExtendOptions>> = IfNotAnyOrNever<TArray,
+	TArray extends readonly [infer First, ...infer Rest]
+		? IsNever<First> extends true
+			? Or<Or<IsNever<Type>, IsAny<Type>>, Not<Options['strictNever']>> extends true
+				// If target `Type` is also `never`, or is `any`, or `strictNever` is disabled, return `true`.
+				? true
+				: _SomeExtend<Rest, Type, Options>
+			: First extends Type
+				? true
+				: _SomeExtend<Rest, Type, Options>
+		: false,
+	false, false>;
+
+export {};

package/source/spread.d.ts

@@ -41,11 +41,7 @@ const bar = {c: false};
 const fooBar = {...foo, ...bar};
 
 type FooBar = Spread<Foo, Bar>;
-// type FooBar = {
-// 	a: number;
-// 	b?: string | number | undefined;
-// 	c: boolean;
-// }
+//=> {a: number; b?: string | number; c: boolean}
 
 declare function baz(argument: FooBar): void;
 

package/source/tagged.d.ts

@@ -121,7 +121,7 @@ const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
 // Without UnwrapTagged, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
-// Attempting to pass an non-Tagged type to UnwrapTagged will raise a type error.
+// Attempting to pass a non-Tagged type to UnwrapTagged will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapTagged<string>;
 ```
@@ -239,7 +239,7 @@ const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
 // Without UnwrapOpaque, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
-// Attempting to pass an non-Opaque type to UnwrapOpaque will raise a type error.
+// Attempting to pass a non-Opaque type to UnwrapOpaque will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapOpaque<string>;