type-fest 4.5.0 → 4.6.0

package/index.d.ts

@@ -50,6 +50,7 @@ export type {IterableElement} from './source/iterable-element';
 export type {Entry} from './source/entry';
 export type {Entries} from './source/entries';
 export type {SetReturnType} from './source/set-return-type';
+export type {SetParameterType} from './source/set-parameter-type';
 export type {Asyncify} from './source/asyncify';
 export type {Simplify} from './source/simplify';
 export type {Jsonify} from './source/jsonify';
@@ -98,6 +99,8 @@ export type {IsNever} from './source/is-never';
 export type {IfNever} from './source/if-never';
 export type {IsUnknown} from './source/is-unknown';
 export type {IfUnknown} from './source/if-unknown';
+export type {ArrayIndices} from './source/array-indices';
+export type {ArrayValues} from './source/array-values';
 
 // Template literal types
 export type {CamelCase} from './source/camel-case';

package/package.json

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

package/readme.md

@@ -154,6 +154,7 @@ Click the type names for complete docs.
 - [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
 - [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
 - [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
+- [`SetParameterType`](source/set-parameter-type.d.ts) - Create a function that replaces some parameters with the given parameters.
 - [`Simplify`](source/simplify.d.ts) - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
 - [`Get`](source/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
 - [`StringKeyOf`](source/string-key-of.d.ts) - Get keys of the given type as strings.
@@ -172,6 +173,8 @@ Click the type names for complete docs.
 - [`IsEqual`](source/is-equal.d.ts) - Returns a boolean for whether the two given types are equal.
 - [`TaggedUnion`](source/tagged-union.d.ts) - Create a union of types that share a common discriminant property.
 - [`IntRange`](source/int-range.d.ts) - Generate a union of numbers.
+- [`ArrayIndices`](source/array-indices.d.ts) - Provides valid indices for a constant array or tuple.
+- [`ArrayValues`](source/array-values.d.ts) - Provides all values for a constant array or tuple.
 
 ### Type Guard
 
@@ -937,6 +940,7 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o
 ## Maintainers
 
 - [Sindre Sorhus](https://github.com/sindresorhus)
+- [Haozheng Li](https://github.com/Emiyaaaaa)
 - [Jarek Radosz](https://github.com/CvX)
 - [Dimitri Benin](https://github.com/BendingBender)
 - [Pelle Wessman](https://github.com/voxpelli)

package/source/array-indices.d.ts

@@ -0,0 +1,23 @@
+/**
+Provides valid indices for a constant array or tuple.
+
+Use-case: This type is useful when working with constant arrays or tuples and you want to enforce type-safety for accessing elements by their indices.
+
+@example
+```
+import type {ArrayIndices, ArrayValues} from 'type-fest';
+
+const weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'] as const;
+
+type Weekday = ArrayIndices<typeof weekdays>;
+type WeekdayName = ArrayValues<typeof weekdays>;
+
+const getWeekdayName = (day: Weekday): WeekdayName => weekdays[day];
+```
+
+@see {@link ArrayValues}
+
+@category Array
+*/
+export type ArrayIndices<Element extends readonly unknown[]> =
+	Exclude<Partial<Element>['length'], Element['length']>;

package/source/array-values.d.ts

@@ -0,0 +1,22 @@
+/**
+Provides all values for a constant array or tuple.
+
+Use-case: This type is useful when working with constant arrays or tuples and you want to enforce type-safety with their values.
+
+@example
+```
+import type {ArrayValues, ArrayIndices} from 'type-fest';
+
+const weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'] as const;
+
+type WeekdayName = ArrayValues<typeof weekdays>;
+type Weekday = ArrayIndices<typeof weekdays>;
+
+const getWeekdayName = (day: Weekday): WeekdayName => weekdays[day];
+```
+
+@see {@link ArrayIndices}
+
+@category Array
+*/
+export type ArrayValues<T extends readonly unknown[]> = T[number];

package/source/last-array-element.d.ts

@@ -13,16 +13,26 @@ const array = ['foo', 2];
 
 typeof lastOf(array);
 //=> number
+
+const array = ['foo', 2] as const;
+
+typeof lastOf(array);
+//=> 2
 ```
 
 @category Array
 @category Template literal
 */
-export type LastArrayElement<Elements extends readonly unknown[]>
-		= number extends Elements['length']
-			? Elements extends ReadonlyArray<infer Element>
-				? Element
-				: never
-			: Elements extends readonly [...any, infer Target]
-				? Target
-				: never;
+export type LastArrayElement<Elements extends readonly unknown[], ElementBeforeTailingSpreadElement = never> =
+	// If the last element of an array is a spread element, the `LastArrayElement` result should be `'the type of the element before the spread element' | 'the type of the spread element'`.
+	Elements extends readonly []
+		? ElementBeforeTailingSpreadElement
+		: Elements extends readonly [...infer U, infer V]
+			? V
+			: Elements extends readonly [infer U, ...infer V]
+				// If we return `V[number] | U` directly, it would be wrong for `[[string, boolean, object, ...number[]]`.
+				// So we need to recurse type `V` and carry over the type of the element before the spread element.
+				? LastArrayElement<V, U>
+				: Elements extends ReadonlyArray<infer U>
+					? U | ElementBeforeTailingSpreadElement
+					: never;

package/source/partial-deep.d.ts

@@ -59,7 +59,7 @@ const partialSettings: PartialDeep<Settings, {recurseIntoArrays: true}> = {
 @category Set
 @category Map
 */
-export type PartialDeep<T, Options extends PartialDeepOptions = {}> = T extends BuiltIns
+export type PartialDeep<T, Options extends PartialDeepOptions = {}> = T extends BuiltIns | (((...arguments_: any[]) => unknown)) | (new (...arguments_: any[]) => unknown)
 	? T
 	: T extends Map<infer KeyType, infer ValueType>
 		? PartialMapDeep<KeyType, ValueType, Options>
@@ -69,19 +69,17 @@ export type PartialDeep<T, Options extends PartialDeepOptions = {}> = T extends
 				? PartialReadonlyMapDeep<KeyType, ValueType, Options>
 				: T extends ReadonlySet<infer ItemType>
 					? PartialReadonlySetDeep<ItemType, Options>
-					: T extends ((...arguments_: any[]) => unknown)
-						? T | undefined
-						: T extends object
-							? T extends ReadonlyArray<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
-								? Options['recurseIntoArrays'] extends true
-									? ItemType[] extends T // Test for arrays (non-tuples) specifically
-										? readonly ItemType[] extends T // Differentiate readonly and mutable arrays
-											? ReadonlyArray<PartialDeep<ItemType | undefined, Options>>
-											: Array<PartialDeep<ItemType | undefined, Options>>
-										: PartialObjectDeep<T, Options> // Tuples behave properly
-									: T // If they don't opt into array testing, just use the original type
-								: PartialObjectDeep<T, Options>
-							: unknown;
+					: T extends object
+						? T extends ReadonlyArray<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
+							? Options['recurseIntoArrays'] extends true
+								? ItemType[] extends T // Test for arrays (non-tuples) specifically
+									? readonly ItemType[] extends T // Differentiate readonly and mutable arrays
+										? ReadonlyArray<PartialDeep<ItemType | undefined, Options>>
+										: Array<PartialDeep<ItemType | undefined, Options>>
+									: PartialObjectDeep<T, Options> // Tuples behave properly
+								: T // If they don't opt into array testing, just use the original type
+							: PartialObjectDeep<T, Options>
+						: unknown;
 
 /**
 Same as `PartialDeep`, but accepts only `Map`s and as inputs. Internal helper for `PartialDeep`.

package/source/readonly-deep.d.ts

@@ -38,28 +38,30 @@ Note that types containing overloaded functions are not made deeply readonly due
 */
 export type ReadonlyDeep<T> = T extends BuiltIns
 	? T
-	: T extends (...arguments_: any[]) => unknown
-		? {} extends ReadonlyObjectDeep<T>
-			? T
-			: HasMultipleCallSignatures<T> extends true
+	: T extends new (...args: any[]) => unknown
+		? T // Skip class constructors
+		: T extends (...arguments_: any[]) => unknown
+			? {} extends ReadonlyObjectDeep<T>
 				? T
-				: ((...arguments_: Parameters<T>) => ReturnType<T>) & ReadonlyObjectDeep<T>
-		: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
-			? ReadonlyMapDeep<KeyType, ValueType>
-			: T extends Readonly<ReadonlySet<infer ItemType>>
-				? ReadonlySetDeep<ItemType>
-				: // Identify tuples to avoid converting them to arrays inadvertently; special case `readonly [...never[]]`, as it emerges undesirably from recursive invocations of ReadonlyDeep below.
-				T extends readonly [] | readonly [...never[]]
-					? readonly []
-					: T extends readonly [infer U, ...infer V]
-						? readonly [ReadonlyDeep<U>, ...ReadonlyDeep<V>]
-						: T extends readonly [...infer U, infer V]
-							? readonly [...ReadonlyDeep<U>, ReadonlyDeep<V>]
-							: T extends ReadonlyArray<infer ItemType>
-								? ReadonlyArray<ReadonlyDeep<ItemType>>
-								: T extends object
-									? ReadonlyObjectDeep<T>
-									: unknown;
+				: HasMultipleCallSignatures<T> extends true
+					? T
+					: ((...arguments_: Parameters<T>) => ReturnType<T>) & ReadonlyObjectDeep<T>
+			: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
+				? ReadonlyMapDeep<KeyType, ValueType>
+				: T extends Readonly<ReadonlySet<infer ItemType>>
+					? ReadonlySetDeep<ItemType>
+					: // Identify tuples to avoid converting them to arrays inadvertently; special case `readonly [...never[]]`, as it emerges undesirably from recursive invocations of ReadonlyDeep below.
+					T extends readonly [] | readonly [...never[]]
+						? readonly []
+						: T extends readonly [infer U, ...infer V]
+							? readonly [ReadonlyDeep<U>, ...ReadonlyDeep<V>]
+							: T extends readonly [...infer U, infer V]
+								? readonly [...ReadonlyDeep<U>, ReadonlyDeep<V>]
+								: T extends ReadonlyArray<infer ItemType>
+									? ReadonlyArray<ReadonlyDeep<ItemType>>
+									: T extends object
+										? ReadonlyObjectDeep<T>
+										: unknown;
 
 /**
 Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.

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

@@ -0,0 +1,68 @@
+import type {IsUnknown} from './is-unknown';
+
+/**
+Create a tuple that replaces the given `Tuple`'s elements with the given `Record_`'s values at the given indices.
+*/
+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]
+};
+
+/**
+Create a function that replaces some parameters with the given parameters.
+
+The parameters that are not specified will be kept as-is.
+
+Note:
+- This type will ignore the given function's generic type.
+- If you change the parameter type that return type depends on, the return type will not change:
+	```
+	const fn = (a: number) => a;
+	//=> fn: (a: number) => number;
+
+ 	// We change type of `a` to `string`, but return type is still `number`.
+	type Fn = SetParameterType<typeof fn, {0: string}>;
+ 	//=> (a: string) => number;
+	```
+
+Use-case:
+- Define a wrapped function that receives something different while returning the same type.
+- Mocking and testing.
+- Overload function type. (See example)
+
+@example
+```
+import type {SetParameterType} from 'type-fest';
+
+type HandleMessage = (data: Data, message: string) => void;
+
+type HandleOk = SetParameterType<HandleMessage, {0: SuccessData, 1: 'ok'}>;
+//=> type HandleOk = (data: SuccessData, message: 'ok') => void;
+
+// Another way to define the parameters to replace.
+type HandleError = SetParameterType<HandleMessage, [data: ErrorData, message: 'error']>;
+//=> type HandleError = (data: ErrorData, message: 'error') => void;
+
+// Could change single parameter type.
+type HandleWarn = SetParameterType<HandleMessage, {1: 'warn'}>;
+//=> type HandleWarn = (data: Data, message: 'warn') => void;
+```
+
+@category Function
+*/
+export type SetParameterType<Fn extends (...arguments_: any[]) => unknown, P extends Record<number, unknown>> =
+	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.
+	Fn extends (this: infer ThisArg, ...arguments_: infer Arguments) => unknown
+		? (
+			// 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>
+		)
+		: Fn;	// This part should be unreachable

package/source/writable-deep.d.ts

@@ -38,23 +38,31 @@ export type WritableDeep<T> = T extends BuiltIns
 			: HasMultipleCallSignatures<T> extends true
 				? T
 				: ((...arguments_: Parameters<T>) => ReturnType<T>) & WritableObjectDeep<T>
-		: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
-			? WritableMapDeep<KeyType, ValueType>
-			: T extends Readonly<ReadonlySet<infer ItemType>>
-				? WritableSetDeep<ItemType>
-				: T extends object
-					? WritableObjectDeep<T>
-					: unknown;
+		: T extends ReadonlyMap<unknown, unknown>
+			? WritableMapDeep<T>
+			: T extends ReadonlySet<unknown>
+				? WritableSetDeep<T>
+				: T extends readonly unknown[]
+					? WritableArrayDeep<T>
+					: T extends object
+						? WritableObjectDeep<T>
+						: unknown;
 
 /**
 Same as `WritableDeep`, but accepts only `Map`s as inputs. Internal helper for `WritableDeep`.
 */
-type WritableMapDeep<KeyType, ValueType> = {} & Writable<Map<WritableDeep<KeyType>, WritableDeep<ValueType>>>;
+type WritableMapDeep<MapType extends ReadonlyMap<unknown, unknown>> =
+	MapType extends ReadonlyMap<infer KeyType, infer ValueType>
+		? Map<WritableDeep<KeyType>, WritableDeep<ValueType>>
+		: MapType; // Should not heppen
 
 /**
 Same as `WritableDeep`, but accepts only `Set`s as inputs. Internal helper for `WritableDeep`.
 */
-type WritableSetDeep<ItemType> = {} & Writable<Set<WritableDeep<ItemType>>>;
+type WritableSetDeep<SetType extends ReadonlySet<unknown>> =
+	SetType extends ReadonlySet<infer ItemType>
+		? Set<WritableDeep<ItemType>>
+		: SetType; // Should not heppen
 
 /**
 Same as `WritableDeep`, but accepts only `object`s as inputs. Internal helper for `WritableDeep`.
@@ -62,3 +70,15 @@ Same as `WritableDeep`, but accepts only `object`s as inputs. Internal helper fo
 type WritableObjectDeep<ObjectType extends object> = {
 	-readonly [KeyType in keyof ObjectType]: WritableDeep<ObjectType[KeyType]>
 };
+
+/**
+Same as `WritableDeep`, but accepts only `Array`s as inputs. Internal helper for `WritableDeep`.
+*/
+type WritableArrayDeep<ArrayType extends readonly unknown[]> =
+	ArrayType extends readonly [] ? []
+		: ArrayType extends readonly [...infer U, infer V] ? [...WritableArrayDeep<U>, WritableDeep<V>]
+			: ArrayType extends readonly [infer U, ...infer V] ? [WritableDeep<U>, ...WritableArrayDeep<V>]
+				: ArrayType extends ReadonlyArray<infer U> ? Array<WritableDeep<U>>
+					: ArrayType extends Array<infer U> ? Array<WritableDeep<U>>
+						: ArrayType;
+