type-fest 4.12.0 → 4.13.0

package/index.d.ts

@@ -6,6 +6,7 @@ export * from './source/observable-like';
 
 // Utilities
 export type {KeysOfUnion} from './source/keys-of-union';
+export type {DistributedOmit} from './source/distributed-omit';
 export type {EmptyObject, IsEmptyObject} from './source/empty-object';
 export type {NonEmptyObject} from './source/non-empty-object';
 export type {UnknownRecord} from './source/unknown-record';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -182,6 +182,7 @@ Click the type names for complete docs.
 - [`SetFieldType`](source/set-field-type.d.ts) - Create a type that changes the type of the given keys.
 - [`Paths`](source/paths.d.ts) - Generate a union of all possible paths to properties in the given object.
 - [`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.
 
 ### Type Guard
 
@@ -323,6 +324,7 @@ 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)
 
 ## Tips
 

package/source/array-slice.d.ts

@@ -1,9 +1,11 @@
 import type {Sum} from './sum';
-import type {LessThan} from './less-than';
 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} from './internal';
+import type {And, Not, ArrayMin} from './internal';
 import type {IsEqual} from './is-equal';
+import type {ArraySplice} from './array-splice';
 
 /**
 Returns an array slice of a given range, just like `Array#slice()`.
@@ -54,9 +56,26 @@ slice[3];
 */
 export type ArraySlice<
 	Array_ extends readonly unknown[],
-	Start extends number = 0,
-	End extends number = Array_['length'],
-> = ArraySliceHelper<Array_, Start, End>;
+	Start extends number = never,
+	End extends number = never,
+> = And<IsEqual<Start, never>, IsEqual<End, never>> extends true
+	? Array_
+	: number extends Array_['length']
+		? VariableLengthArraySliceHelper<Array_, Start, End>
+		: ArraySliceHelper<Array_, IsEqual<Start, never> extends true ? 0 : Start, IsEqual<End, never> extends true ? Array_['length'] : End>;
+
+type VariableLengthArraySliceHelper<
+	Array_ extends readonly unknown[],
+	Start extends number,
+	End extends number,
+> = And<Not<IsNegative<Start>>, IsEqual<End, never>> extends true
+	? ArraySplice<Array_, 0, Start>
+	: And<
+	And<Not<IsNegative<Start>>, Not<IsNegative<End>>>,
+	IsEqual<GreaterThan<End, Start>, true>
+	> extends true
+		? ArraySliceByPositiveIndex<Array_, Start, End>
+		: [];
 
 type ArraySliceHelper<
 	Array_ extends readonly unknown[],
@@ -73,21 +92,15 @@ type ArraySliceHelper<
 			: never
 		: Start,
 	PositiveE extends number = IsNegative<End> extends true ? Sum<ArrayLength, End> : End,
-> = true extends [IsNegative<PositiveS>, LessThanOrEqual<PositiveE, PositiveS>][number]
+> = true extends [IsNegative<PositiveS>, LessThanOrEqual<PositiveE, PositiveS>, GreaterThanOrEqual<PositiveS, ArrayLength>][number]
 	? []
-	: ArraySliceByPositiveIndex<Array_, PositiveS, PositiveE>;
+	: ArraySliceByPositiveIndex<Array_, ArrayMin<[PositiveS, ArrayLength]>, ArrayMin<[PositiveE, ArrayLength]>>;
 
 type ArraySliceByPositiveIndex<
 	Array_ extends readonly unknown[],
 	Start extends number,
 	End extends number,
-	TraversedElement extends Array<Array_[number]> = [],
 	Result extends Array<Array_[number]> = [],
-> = Array_ extends readonly [infer H, ...infer Rest]
-	? And<
-	IsEqual<LessThanOrEqual<Start, TraversedElement['length']>, true>,
-	IsEqual<LessThan<TraversedElement['length'], End>, true>
-	> extends true
-		? ArraySliceByPositiveIndex<Rest, Start, End, [...TraversedElement, H], [...Result, H]>
-		: ArraySliceByPositiveIndex<Rest, Start, End, [...TraversedElement, H], Result>
-	: Result;
+> = Start extends End
+	? Result
+	: ArraySliceByPositiveIndex<Array_, Sum<Start, 1>, End, [...Result, Array_[Start]]>;

package/source/distributed-omit.d.ts

@@ -0,0 +1,89 @@
+import type {KeysOfUnion} from './keys-of-union';
+
+/**
+Omits keys from a type, distributing the operation over a union.
+
+TypeScript's `Omit` doesn't distribute over unions, leading to the erasure of unique properties from union members when omitting keys. This creates a type that only retains properties common to all union members, making it impossible to access member-specific properties after the Omit. Essentially, using `Omit` on a union type merges the types into a less specific one, hindering type narrowing and property access based on discriminants. This type solves that.
+
+Example:
+
+```
+type A = {
+	discriminant: 'A';
+	foo: string;
+	a: number;
+};
+
+type B = {
+	discriminant: 'B';
+	foo: string;
+	b: string;
+};
+
+type Union = A | B;
+
+type OmittedUnion = Omit<Union, 'foo'>;
+//=> {discriminant: 'A' | 'B'}
+
+const omittedUnion: OmittedUnion = createOmittedUnion();
+
+if (omittedUnion.discriminant === 'A') {
+	// We would like to narrow `omittedUnion`'s type
+	// to `A` here, but we can't because `Omit`
+	// doesn't distribute over unions.
+
+	omittedUnion.a;
+ 	//=> Error: `a` is not a property of `{discriminant: 'A' | 'B'}`
+}
+```
+
+While `Except` solves this problem, it restricts the keys you can omit to the ones that are present in **ALL** union members, where `DistributedOmit` allows you to omit keys that are present in **ANY** union member.
+
+@example
+```
+type A = {
+	discriminant: 'A';
+	foo: string;
+	a: number;
+};
+
+type B = {
+	discriminant: 'B';
+	foo: string;
+	bar: string;
+	b: string;
+};
+
+type C = {
+	discriminant: 'C';
+	bar: string;
+	c: boolean;
+};
+
+// Notice that `foo` exists in `A` and `B`, but not in `C`, and
+// `bar` exists in `B` and `C`, but not in `A`.
+
+type Union = A | B | C;
+
+type OmittedUnion = DistributedOmit<Union, 'foo' | 'bar'>;
+
+const omittedUnion: OmittedUnion = createOmittedUnion();
+
+if (omittedUnion.discriminant === 'A') {
+	omittedUnion.a;
+ 	//=> OK
+
+	omittedUnion.foo;
+ 	//=> Error: `foo` is not a property of `{discriminant: 'A'; a: string}`
+
+	omittedUnion.bar;
+ 	//=> Error: `bar` is not a property of `{discriminant: 'A'; a: string}`
+}
+```
+
+@category Object
+*/
+export type DistributedOmit<ObjectType, KeyType extends KeysOfUnion<ObjectType>> =
+	ObjectType extends unknown
+		? Omit<ObjectType, KeyType>
+		: never;

package/source/omit-deep.d.ts

@@ -1,6 +1,8 @@
 import type {ArraySplice} from './array-splice';
 import type {ExactKey, IsArrayReadonly, NonRecursiveType, SetArrayAccess, ToString} from './internal';
 import type {IsEqual} from './is-equal';
+import type {IsNever} from './is-never';
+import type {LiteralUnion} from './literal-union';
 import type {SimplifyDeep} from './merge-deep';
 import type {Paths} from './paths';
 import type {SharedUnionFieldsDeep} from './shared-union-fields-deep';
@@ -69,7 +71,7 @@ type AddressInfo = OmitDeep<Info1, 'address.1.foo'>;
 @category Object
 @category Array
 */
-export type OmitDeep<T, PathUnion extends Paths<T>> =
+export type OmitDeep<T, PathUnion extends LiteralUnion<Paths<T>, string>> =
 	SimplifyDeep<
 	SharedUnionFieldsDeep<
 	{[P in PathUnion]: OmitDeepWithOnePath<T, P>}[PathUnion]
@@ -102,9 +104,11 @@ P extends `${infer RecordKeyInPath}.${infer SubPath}`
 			: ObjectT[Key]
 	}
 	: ExactKey<ObjectT, P> extends infer Key
-		? Key extends PropertyKey
-			? Omit<ObjectT, Key>
-			: ObjectT
+		? IsNever<Key> extends true
+			? ObjectT
+			: Key extends PropertyKey
+				? Omit<ObjectT, Key>
+				: ObjectT
 		: ObjectT;
 
 /**
@@ -133,4 +137,4 @@ type OmitDeepArrayWithOnePath<ArrayType extends UnknownArray, P extends string |
 				? []
 				// If `ArrayIndex` is a number literal
 				: ArraySplice<ArrayType, ArrayIndex, 1, [unknown]>
-			: never;
+			: ArrayType;

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

@@ -1,17 +1,53 @@
 import type {IsUnknown} from './is-unknown';
+import type {StaticPartOfArray} from './internal';
+import type {UnknownArray} from './unknown-array';
 
 /**
-Create a tuple that replaces the given `Tuple`'s elements with the given `Record_`'s values at the given indices.
+Create an array that replaces the given `TArray`'s elements with the given `TObject`'s values at the given indices.
+
+`TArray` and `TObject` supports tailing spread array like `[string, ...boolean[]]`, but does not support `[string, ...boolean[], number]`.
+
+@example:
+```ts
+// object
+type A = MergeObjectToArray<[string, number], {0: boolean}>;
+//=> [boolean, number]
+
+// array
+type B = MergeObjectToArray<[string, number], [boolean]>;
+//=> [boolean, number]
+
+// tailing spread array
+type C = MergeObjectToArray<[string, ...boolean[]], {1: number}>;
+//=> [string, ...number[]]
+
+type D = MergeObjectToArray<[string, ...boolean[]], [number, ...string[]]>;
+//=> [number, ...string[]]
+```
 */
-type MergeObjectToTuple<Tuple extends unknown[], Record_ extends Record<number, unknown>> = {
-	[K in keyof Tuple]: Record_ extends Record<string, unknown>
-		// Handle object case like `{0: string, 1: number}`
-		? K extends `${infer NumberK extends number}`
-			? NumberK extends keyof Record_ ? Record_[K] : Tuple[K]
-			: never // Should not happen
-		// Handle tuple case like `[string, number]`
-		: K extends keyof Record_ ? Record_[K] : Tuple[K]
-};
+type MergeObjectToArray<TArray extends UnknownArray, TObject, TArrayCopy extends UnknownArray = TArray> =
+	// If `TObject` is an array like `[0, 1, 2]`
+	TObject extends UnknownArray
+		// If `TObject` is a variable length array, we should use `TObject`'s type as the result type.
+		? number extends TObject['length']
+			? TObject
+			: {
+				[K in keyof TArray]: 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}`
+			? {
+				[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[]]`
+						? StaticPartOfArray<TArrayCopy>['length'] extends keyof TObject
+							? TObject[StaticPartOfArray<TArrayCopy>['length']]
+							: TArray[K]
+						: never
+			} : never;
 
 /**
 Create a function that replaces some parameters with the given parameters.
@@ -39,7 +75,7 @@ Use-case:
 ```
 import type {SetParameterType} from 'type-fest';
 
-type HandleMessage = (data: Data, message: string) => void;
+type HandleMessage = (data: Data, message: string, ...arguments: any[]) => void;
 
 type HandleOk = SetParameterType<HandleMessage, {0: SuccessData, 1: 'ok'}>;
 //=> type HandleOk = (data: SuccessData, message: 'ok') => void;
@@ -48,9 +84,19 @@ type HandleOk = SetParameterType<HandleMessage, {0: SuccessData, 1: 'ok'}>;
 type HandleError = SetParameterType<HandleMessage, [data: ErrorData, message: 'error']>;
 //=> type HandleError = (data: ErrorData, message: 'error') => void;
 
-// Could change single parameter type.
+// Change single parameter type.
 type HandleWarn = SetParameterType<HandleMessage, {1: 'warn'}>;
 //=> type HandleWarn = (data: Data, message: 'warn') => void;
+
+// Change rest parameter type.
+
+// Way 1: Input full parameter type.
+type HandleLog = SetParameterType<HandleMessage, [data: Data, message: 'log', ...arguments: string[]]>;
+//=> type HandleLog = (data: Data, message: 'log', ...arguments: string[]) => void;
+
+// Way 2: Input rest parameter type by Object index.
+type HandleLog2 = SetParameterType<HandleMessage, {2: string}>;
+//=> type HandleLog2 = (data: Data, message: string, ...arguments: string[]) => void;
 ```
 
 @category Function
@@ -62,7 +108,7 @@ export type SetParameterType<Fn extends (...arguments_: any[]) => unknown, P ext
 			// If a function did not specify the `this` fake parameter, it will be inferred to `unknown`.
 			// We want to detect this situation just to display a friendlier type upon hovering on an IntelliSense-powered IDE.
 			IsUnknown<ThisArg> extends true
-				? (...arguments_: MergeObjectToTuple<Arguments, P>) => ReturnType<Fn>
-				: (this: ThisArg, ...arguments_: MergeObjectToTuple<Arguments, P>) => ReturnType<Fn>
+				? (...arguments_: MergeObjectToArray<Arguments, P>) => ReturnType<Fn>
+				: (this: ThisArg, ...arguments_: MergeObjectToArray<Arguments, P>) => ReturnType<Fn>
 		)
 		: Fn;	// This part should be unreachable

package/source/subtract.d.ts

@@ -34,33 +34,35 @@ Subtract<PositiveInfinity, PositiveInfinity>;
 @category Numeric
 */
 // TODO: Support big integer and negative number.
-export type Subtract<A extends number, B extends number> = [
-	IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
-	IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
-] extends infer R extends [boolean, boolean, boolean, boolean]
-	? Or<
-	And<IsEqual<R[0], true>, IsEqual<R[2], false>>,
-	And<IsEqual<R[3], true>, IsEqual<R[1], false>>
-	> extends true
-		? PositiveInfinity
-		: Or<
-		And<IsEqual<R[1], true>, IsEqual<R[3], false>>,
-		And<IsEqual<R[2], true>, IsEqual<R[0], false>>
+export type Subtract<A extends number, B extends number> = number extends A | B
+	? number
+	: [
+		IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
+		IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
+	] extends infer R extends [boolean, boolean, boolean, boolean]
+		? Or<
+		And<IsEqual<R[0], true>, IsEqual<R[2], false>>,
+		And<IsEqual<R[3], true>, IsEqual<R[1], false>>
 		> extends true
-			? NegativeInfinity
-			: true extends R[number]
-				? number
-				: [IsNegative<A>, IsNegative<B>] extends infer R
-					? [false, false] extends R
-						? BuildTuple<A> extends infer R
-							? R extends [...BuildTuple<B>, ...infer R]
-								? R['length']
-								: number
-							: never
-						: LessThan<A, B> extends true
-							? number
-							: [false, true] extends R
-								? Sum<A, NumberAbsolute<B>>
-								: Subtract<NumberAbsolute<B>, NumberAbsolute<A>>
-					: never
-	: never;
+			? PositiveInfinity
+			: Or<
+			And<IsEqual<R[1], true>, IsEqual<R[3], false>>,
+			And<IsEqual<R[2], true>, IsEqual<R[0], false>>
+			> extends true
+				? NegativeInfinity
+				: true extends R[number]
+					? number
+					: [IsNegative<A>, IsNegative<B>] extends infer R
+						? [false, false] extends R
+							? BuildTuple<A> extends infer R
+								? R extends [...BuildTuple<B>, ...infer R]
+									? R['length']
+									: number
+								: never
+							: LessThan<A, B> extends true
+								? number
+								: [false, true] extends R
+									? Sum<A, NumberAbsolute<B>>
+									: Subtract<NumberAbsolute<B>, NumberAbsolute<A>>
+						: never
+		: never;

package/source/sum.d.ts

@@ -34,33 +34,35 @@ Sum<PositiveInfinity, NegativeInfinity>;
 @category Numeric
 */
 // TODO: Support big integer and negative number.
-export type Sum<A extends number, B extends number> = [
-	IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
-	IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
-] extends infer R extends [boolean, boolean, boolean, boolean]
-	? Or<
-	And<IsEqual<R[0], true>, IsEqual<R[3], false>>,
-	And<IsEqual<R[2], true>, IsEqual<R[1], false>>
-	> extends true
-		? PositiveInfinity
-		: Or<
-		And<IsEqual<R[1], true>, IsEqual<R[2], false>>,
-		And<IsEqual<R[3], true>, IsEqual<R[0], false>>
+export type Sum<A extends number, B extends number> = number extends A | B
+	? number
+	: [
+		IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
+		IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
+	] extends infer R extends [boolean, boolean, boolean, boolean]
+		? Or<
+		And<IsEqual<R[0], true>, IsEqual<R[3], false>>,
+		And<IsEqual<R[2], true>, IsEqual<R[1], false>>
 		> extends true
-			? NegativeInfinity
-			: true extends R[number]
-				? number
-				: ([IsNegative<A>, IsNegative<B>] extends infer R
-					? [false, false] extends R
-						? [...BuildTuple<A>, ...BuildTuple<B>]['length']
-						: [true, true] extends R
-							? number
-							: ArrayMax<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Max_
-								? ArrayMin<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Min_ extends number
-									? Max_ extends A | B
-										? Subtract<Max_, Min_>
-										: number
+			? PositiveInfinity
+			: Or<
+			And<IsEqual<R[1], true>, IsEqual<R[2], false>>,
+			And<IsEqual<R[3], true>, IsEqual<R[0], false>>
+			> extends true
+				? NegativeInfinity
+				: true extends R[number]
+					? number
+					: ([IsNegative<A>, IsNegative<B>] extends infer R
+						? [false, false] extends R
+							? [...BuildTuple<A>, ...BuildTuple<B>]['length']
+							: [true, true] extends R
+								? number
+								: ArrayMax<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Max_
+									? ArrayMin<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Min_ extends number
+										? Max_ extends A | B
+											? Subtract<Max_, Min_>
+											: number
+										: never
 									: never
-								: never
-					: never) & number
-	: never;
+						: never) & number
+		: never;