type-fest 5.4.4 → 5.6.0

package/source/internal/array.d.ts

@@ -4,13 +4,6 @@ import type {OptionalKeysOf} from '../optional-keys-of.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
 import type {IsExactOptionalPropertyTypesEnabled, IfNotAnyOrNever} from './type.d.ts';
 
-/**
-Infer the length of the given array `<T>`.
-
-@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
-*/
-type ArrayLength<T extends readonly unknown[]> = T extends {readonly length: infer L} ? L : never;
-
 /**
 Matches any unknown array or tuple.
 */
@@ -36,8 +29,8 @@ type B = StaticPartOfArray<A>;
 */
 export type StaticPartOfArray<T extends UnknownArray, Result extends UnknownArray = []> =
 	T extends unknown
-		? number extends T['length'] ?
-			T extends readonly [infer U, ...infer V]
+		? number extends T['length']
+			? T extends readonly [infer U, ...infer V]
 				? StaticPartOfArray<V, [...Result, U]>
 				: Result
 			: T
@@ -76,11 +69,11 @@ type NormalResult = SetArrayAccess<ReadonlyStringArray, false>;
 ```
 */
 export type SetArrayAccess<T extends UnknownArray, IsReadonly extends boolean> =
-T extends readonly [...infer U] ?
-	IsReadonly extends true
-		? readonly [...U]
-		: [...U]
-	: T;
+	T extends readonly [...infer U]
+		? IsReadonly extends true
+			? readonly [...U]
+			: [...U]
+		: T;
 
 /**
 Returns whether the given array `T` is readonly.

package/source/internal/keys.d.ts

@@ -87,14 +87,14 @@ type Key4 = ExactKey<Object, 1>;
 @category Object
 */
 export type ExactKey<T extends object, Key extends PropertyKey> =
-Key extends keyof T
-	? Key
-	: ToString<Key> extends keyof T
-		? ToString<Key>
-		: Key extends `${infer NumberKey extends number}`
-			? NumberKey extends keyof T
-				? NumberKey
-				: never
-			: never;
+	Key extends keyof T
+		? Key
+		: ToString<Key> extends keyof T
+			? ToString<Key>
+			: Key extends `${infer NumberKey extends number}`
+				? NumberKey extends keyof T
+					? NumberKey
+					: never
+				: never;
 
 export {};

package/source/internal/numeric.d.ts

@@ -1,26 +1,8 @@
 import type {IsNever} from '../is-never.d.ts';
 import type {Finite, NegativeInfinity, PositiveInfinity} from '../numeric.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
-import type {StringToNumber} from './string.d.ts';
 import type {IfNotAnyOrNever, IsAnyOrNever} from './type.d.ts';
 
-/**
-Returns the absolute value of a given value.
-
-@example
-```
-type A = NumberAbsolute<-1>;
-//=> 1
-
-type B = NumberAbsolute<1>;
-//=> 1
-
-type C = NumberAbsolute<NegativeInfinity>;
-//=> PositiveInfinity
-```
-*/
-export type NumberAbsolute<N extends number> = `${N}` extends `-${infer StringPositiveN}` ? StringToNumber<StringPositiveN> : N;
-
 /**
 Check whether the given type is a number or a number string.
 
@@ -142,10 +124,18 @@ type D = ReverseSign<PositiveInfinity>;
 */
 export type ReverseSign<N extends number> =
 	// Handle edge cases
-	N extends 0 ? 0 : N extends PositiveInfinity ? NegativeInfinity : N extends NegativeInfinity ? PositiveInfinity :
-	// Handle negative numbers
-	`${N}` extends `-${infer P extends number}` ? P
-		// Handle positive numbers
-		: `-${N}` extends `${infer R extends number}` ? R : never;
+	N extends 0
+		? 0
+		: N extends PositiveInfinity
+			? NegativeInfinity
+			: N extends NegativeInfinity
+				? PositiveInfinity
+				// Handle negative numbers
+				: `${N}` extends `-${infer P extends number}`
+					? P
+					// Handle positive numbers
+					: `-${N}` extends `${infer R extends number}`
+						? R
+						: never;
 
 export {};

package/source/internal/tuple.d.ts

@@ -23,7 +23,7 @@ type Union = TupleLength<[] | [1, 2, 3] | number[]>;
 */
 export type TupleLength<T extends UnknownArray> =
 	// `extends unknown` is used to convert `T` (if `T` is a union type) to
-	// a [distributive conditionaltype](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types))
+	// a [distributive conditional type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types))
 	T extends unknown
 		? number extends T['length']
 			? never // Return never if the given type is an non-flexed-length array like `Array<string>`
@@ -46,8 +46,8 @@ type B = TupleMax<[1, 2, 5, 3, 99, -1]>;
 ```
 */
 export type TupleMax<A extends number[], Result extends number = NegativeInfinity> = number extends A[number]
-	? never :
-	A extends [infer F extends number, ...infer R extends number[]]
+	? never
+	: A extends [infer F extends number, ...infer R extends number[]]
 		? GreaterThan<F, Result> extends true
 			? TupleMax<R, F>
 			: TupleMax<R, Result>

package/source/internal/type.d.ts

@@ -3,6 +3,7 @@ import type {IsAny} from '../is-any.d.ts';
 import type {IsNever} from '../is-never.d.ts';
 import type {Primitive} from '../primitive.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
+import type {UnionToIntersection} from '../union-to-intersection.d.ts';
 
 /**
 Matches any primitive, `void`, `Date`, or `RegExp` value.

package/source/is-equal.d.ts

@@ -1,4 +1,3 @@
-import type {IsNever} from './is-never.d.ts';
 /**
 Returns a boolean for whether the two given types are equal.
 

package/source/is-integer.d.ts

@@ -47,14 +47,14 @@ type J = IsInteger<1e-7>;
 @category Numeric
 */
 export type IsInteger<T> =
-T extends bigint
-	? true
-	: T extends number
-		? number extends T
-			? false
-			: T extends PositiveInfinity | NegativeInfinity
+	T extends bigint
+		? true
+		: T extends number
+			? number extends T
 				? false
-				: Not<IsFloat<T>>
-		: false;
+				: T extends PositiveInfinity | NegativeInfinity
+					? false
+					: Not<IsFloat<T>>
+			: false;
 
 export {};

package/source/is-literal.d.ts

@@ -121,11 +121,11 @@ export type IsStringLiteral<S> = IfNotAnyOrNever<S,
 export type _IsStringLiteral<S> =
 // If `T` is an infinite string type (e.g., `on${string}`), `Record<T, never>` produces an index signature,
 // and since `{}` extends index signatures, the result becomes `false`.
-S extends string
-	? {} extends Record<S, never>
-		? false
-		: true
-	: false;
+	S extends string
+		? {} extends Record<S, never>
+			? false
+			: true
+		: false;
 
 /**
 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).

package/source/is-union.d.ts

@@ -21,20 +21,20 @@ export type IsUnion<T> = InternalIsUnion<T>;
 The actual implementation of `IsUnion`.
 */
 type InternalIsUnion<T, U = T> =
-(
-	IsNever<T> extends true
-		? false
-		: T extends any
-			? IsEqual<U, T> extends true
-				? false
-				: true
-			: never
-) extends infer Result
+	(
+		IsNever<T> extends true
+			? false
+			: T extends any
+				? IsEqual<U, T> extends true
+					? false
+					: true
+				: never
+	) extends infer Result
 	// In some cases `Result` will return `false | true` which is `boolean`,
 	// that means `T` has at least two types and it's a union type,
 	// so we will return `true` instead of `boolean`.
-	? boolean extends Result ? true
-		: Result
-	: never; // Should never happen
+		? boolean extends Result ? true
+			: Result
+		: never; // Should never happen
 
 export {};

package/source/iterable-element.d.ts

@@ -57,10 +57,10 @@ type Fruit = IterableElement<typeof fruits>;
 @category Iterable
 */
 export type IterableElement<TargetIterable> =
-	TargetIterable extends Iterable<infer ElementType> ?
-		ElementType :
-		TargetIterable extends AsyncIterable<infer ElementType> ?
-			ElementType :
-			never;
+	TargetIterable extends Iterable<infer ElementType>
+		? ElementType
+		: TargetIterable extends AsyncIterable<infer ElementType>
+			? ElementType
+			: never;
 
 export {};

package/source/jsonify.d.ts

@@ -98,13 +98,13 @@ export type Jsonify<T> = IsAny<T> extends true
 		? null
 		: T extends JsonPrimitive
 			? T
-			: // Any object with toJSON is special case
-			T extends {toJSON(): infer J}
+			// Any object with toJSON is special case
+			: T extends {toJSON(): infer J}
 				? (() => J) extends () => JsonValue // Is J assignable to JsonValue?
 					? J // Then T is Jsonable and its Jsonable value is J
 					: Jsonify<J> // Maybe if we look a level deeper we'll find a JsonValue
-				: // Instanced primitives are objects
-				T extends Number
+				// Instanced primitives are objects
+				: T extends Number
 					? number
 					: T extends String
 						? string

package/source/kebab-case.d.ts

@@ -15,6 +15,7 @@ import type {KebabCase} from 'type-fest';
 
 const someVariable: KebabCase<'fooBar'> = 'foo-bar';
 const someVariableNoSplitOnNumbers: KebabCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p-network';
+const someVariableWithPunctuation: KebabCase<'div.card::after', {splitOnPunctuation: true}> = 'div-card-after';
 
 // Advanced
 

package/source/kebab-cased-properties-deep.d.ts

@@ -51,6 +51,13 @@ const splitOnNumbers: KebabCasedPropertiesDeep<{line1: {line2: [{line3: string}]
 		],
 	},
 };
+
+const splitOnPunctuation: KebabCasedPropertiesDeep<{'user@info': {'user::id': number; 'user::name': string}}, {splitOnPunctuation: true}> = {
+	'user-info': {
+		'user-id': 1,
+		'user-name': 'Tom',
+	},
+};
 ```
 
 @category Change case

package/source/kebab-cased-properties.d.ts

@@ -4,7 +4,7 @@ import type {ApplyDefaultOptions} from './internal/index.d.ts';
 import type {WordsOptions} from './words.d.ts';
 
 /**
-Convert object properties to kebab case but not recursively.
+Convert top-level object properties to kebab case.
 
 This can be useful when, for example, converting some API types from a different style.
 
@@ -28,6 +28,10 @@ const result: KebabCasedProperties<User> = {
 const splitOnNumbers: KebabCasedProperties<{line1: string}, {splitOnNumbers: true}> = {
 	'line-1': 'string',
 };
+
+const splitOnPunctuation: KebabCasedProperties<{'foo::bar': string}, {splitOnPunctuation: true}> = {
+	'foo-bar': 'string',
+};
 ```
 
 @category Change case

package/source/keys-of-union.d.ts

@@ -38,7 +38,7 @@ type AllKeys = KeysOfUnion<Union>;
 @category Object
 */
 export type KeysOfUnion<ObjectType> =
-  // Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
-  keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
+	// Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
+	keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
 
 export {};

package/source/less-than-or-equal.d.ts

@@ -1,7 +1,7 @@
 import type {GreaterThan} from './greater-than.d.ts';
 
 /**
- Returns a boolean for whether a given number is less than or equal to another number.
+Returns a boolean for whether a given number is less than or equal to another number.
 
 @example
 ```
@@ -16,9 +16,45 @@ type B = LessThanOrEqual<1, 1>;
 type C = LessThanOrEqual<1, 5>;
 //=> true
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {LessThanOrEqual} from 'type-fest';
+
+type A = LessThanOrEqual<number, 1>;
+//=> boolean
+
+type B = LessThanOrEqual<1, number>;
+//=> boolean
+
+type C = LessThanOrEqual<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {LessThanOrEqual} from 'type-fest';
+
+// Use `LessThanOrEqual` to constrain a function parameter to non-positive numbers.
+declare function setNonPositive<N extends number>(value: LessThanOrEqual<N, 0> extends true ? N : never): void;
+
+setNonPositive(0); // ✅ Allowed
+setNonPositive(-1); // ✅ Allowed
+
+// @ts-expect-error
+setNonPositive(1);
+
+// @ts-expect-error
+setNonPositive(2);
+```
 */
-export type LessThanOrEqual<A extends number, B extends number> = number extends A | B
-	? never
-	: GreaterThan<A, B> extends true ? false : true;
+export type LessThanOrEqual<A extends number, B extends number> =
+	GreaterThan<A, B> extends infer Result
+		? Result extends true
+			? false
+			: true
+		: never; // Should never happen
 
 export {};

package/source/less-than.d.ts

@@ -16,10 +16,42 @@ type B = LessThan<1, 1>;
 type C = LessThan<1, 5>;
 //=> true
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {LessThan} from 'type-fest';
+
+type A = LessThan<number, 1>;
+//=> boolean
+
+type B = LessThan<1, number>;
+//=> boolean
+
+type C = LessThan<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {LessThan} from 'type-fest';
+
+// Use `LessThan` to constrain a function parameter to negative numbers.
+declare function setNegative<N extends number>(value: LessThan<N, 0> extends true ? N : never): void;
+
+setNegative(-1); // ✅ Allowed
+setNegative(-2); // ✅ Allowed
+
+// @ts-expect-error
+setNegative(0);
+
+// @ts-expect-error
+setNegative(1);
+```
 */
-export type LessThan<A extends number, B extends number> = number extends A | B
-	? never
-	: GreaterThanOrEqual<A, B> extends infer Result
+export type LessThan<A extends number, B extends number> =
+	GreaterThanOrEqual<A, B> extends infer Result
 		? Result extends true
 			? false
 			: true

package/source/literal-to-primitive.d.ts

@@ -1,5 +1,5 @@
 /**
-Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the {@link Primitive | primitive type} it belongs to, or `never` if it's not a primitive.
+Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the [primitive type](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) it belongs to, or `never` if it's not a primitive.
 
 Use-case: Working with generic types that may be literal types.
 

package/source/literal-union.d.ts

@@ -3,7 +3,7 @@ import type {Primitive} from './primitive.d.ts';
 export type _LiteralStringUnion<T> = LiteralUnion<T, string>;
 
 /**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+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.
 
 Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
 

package/source/merge-exclusive.d.ts

@@ -38,8 +38,8 @@ exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 @category Object
 */
 export type MergeExclusive<FirstType, SecondType> =
-	(FirstType | SecondType) extends object ?
-		(Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType) :
-		FirstType | SecondType;
+	(FirstType | SecondType) extends object
+		? (Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType)
+		: FirstType | SecondType;
 
 export {};

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/multidimensional-array.d.ts

@@ -4,7 +4,7 @@ import type {IsEqual} from './is-equal.d.ts';
 type Recursive<T> = Array<Recursive<T>>;
 
 /**
-Creates a type that represents a multidimensional array of the given type and dimension.
+Create a type that represents a multidimensional array of the given type and dimension.
 
 Use-cases:
 - Return a n-dimensional array from functions.

package/source/multidimensional-readonly-array.d.ts

@@ -4,7 +4,7 @@ import type {IsEqual} from './is-equal.d.ts';
 type Recursive<T> = ReadonlyArray<Recursive<T>>;
 
 /**
-Creates a type that represents a multidimensional readonly array that of the given type and dimension.
+Create a type that represents a multidimensional readonly array of the given type and dimension.
 
 Use-cases:
 - Return a n-dimensional array from functions.

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

@@ -0,0 +1,102 @@
+import type {BuiltIns, HasMultipleCallSignatures} from './internal/type.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+/**
+Recursively removes `null` and `undefined` from the specified type.
+
+Use-cases:
+- Normalizing data received from external sources where `null`/`undefined` have been cleaned.
+- Creating non-nullable variants of deeply nested types.
+
+NOTE: Optional modifiers (`?`) are not removed from properties. For example, `NonNullableDeep<{foo?: string | null | undefined}>` will result in `{foo?: string}`. To remove both optional modifiers and nullables, use {@link RequiredDeep} in conjunction with this type.
+
+@example
+```
+import type {NonNullableDeep} from 'type-fest';
+
+type UserDraft = {
+	name: string | null;
+	address: {
+		city: string | undefined;
+		postalCode: string | null;
+		landmark?: string | undefined;
+	};
+	tags: Array<string | null>;
+	visits: Map<string | null, {
+		date: Date | null;
+		notes: Set<string | undefined>;
+	}>;
+};
+
+type User = NonNullableDeep<UserDraft>;
+//=> {
+// 	name: string;
+// 	address: {
+// 		city: string;
+// 		postalCode: string;
+// 		landmark?: string;
+// 	};
+// 	tags: string[];
+// 	visits: Map<string, {
+// 		date: Date;
+// 		notes: Set<string>;
+// 	}>;
+// }
+```
+
+@example
+```
+import type {NonNullableDeep} from 'type-fest';
+
+type ArrayExample = NonNullableDeep<[{a: number | undefined}, ...Array<{b: string | null}>]>;
+//=> [{a: number}, ...{b: string}[]]
+
+type MapExample = NonNullableDeep<{a: Map<{a: string | null}, {c: number | undefined}>}>;
+//=> {a: Map<{a: string}, {c: number}>}
+
+type SetExample = NonNullableDeep<Set<{a: string | null}> | null | undefined>;
+//=> Set<{a: string}>
+
+type PromiseExample = NonNullableDeep<{a: Promise<{b: string | null}>}>;
+//=> {a: Promise<{b: string}>}
+
+type FunctionExample = NonNullableDeep<(a: string | null) => number | undefined>;
+//=> (a: string) => number
+```
+
+@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+export type NonNullableDeep<T> =
+	T extends BuiltIns | (new (...arguments_: any[]) => unknown)
+		? Exclude<T, null | undefined> // `Exclude` is used instead of `NonNullable` because `NonNullable<void>` results in `void & {}`.
+		: T extends Map<infer KeyType, infer ValueType>
+			? Map<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+			: T extends Set<infer ItemType>
+				? Set<NonNullableDeep<ItemType>>
+				: T extends ReadonlyMap<infer KeyType, infer ValueType>
+					? ReadonlyMap<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+					: T extends ReadonlySet<infer ItemType>
+						? ReadonlySet<NonNullableDeep<ItemType>>
+						: T extends WeakMap<infer KeyType, infer ValueType>
+							? WeakMap<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+							: T extends WeakSet<infer ItemType>
+								? WeakSet<NonNullableDeep<ItemType>>
+								: T extends Promise<infer ValueType>
+									? Promise<NonNullableDeep<ValueType>>
+									: T extends (...arguments_: any[]) => unknown
+										? HasMultipleCallSignatures<T> extends true
+											? T
+											: ((...arguments_: NonNullableDeep<Parameters<T>>) => NonNullableDeep<ReturnType<T>>)
+												& (IsNever<keyof T> extends true
+													? unknown
+													: NonNullableDeep<Simplify<T>>) // `Simplify` removes the call signature
+										: T extends object
+											? {[P in keyof T]: NonNullableDeep<T[P]>}
+											: unknown;
+
+export {};

package/source/numeric.d.ts

@@ -121,9 +121,9 @@ declare function setPercentage<T extends number>(length: Float<T>): void;
 @category Numeric
 */
 export type Float<T> =
-T extends unknown // To distributive type
-	? IsFloat<T> extends true ? T : never
-	: never; // Never happens
+	T extends unknown // To distributive type
+		? IsFloat<T> extends true ? T : never
+		: never; // Never happens
 
 /**
 A negative (`-∞ < x < 0`) `number` that is not an integer.