type-fest 4.30.2 → 4.32.0

package/index.d.ts

@@ -42,6 +42,7 @@ export type {InvariantOf} from './source/invariant-of';
 export type {SetOptional} from './source/set-optional';
 export type {SetReadonly} from './source/set-readonly';
 export type {SetRequired} from './source/set-required';
+export type {SetRequiredDeep} from './source/set-required-deep';
 export type {SetNonNullable} from './source/set-non-nullable';
 export type {ValueOf} from './source/value-of';
 export type {AsyncReturnType} from './source/async-return-type';
@@ -121,6 +122,7 @@ 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 {IsTuple} from './source/is-tuple';
 export type {ArrayIndices} from './source/array-indices';
 export type {ArrayValues} from './source/array-values';
 export type {ArraySlice} from './source/array-slice';

package/package.json

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

package/readme.md

@@ -159,6 +159,7 @@ Click the type names for complete docs.
 - [`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.
 - [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
+- [`SetRequiredDeep`](source/set-required-deep.d.ts) - Like `SetRequired` except it selects the keys deeply.
 - [`SetNonNullable`](source/set-non-nullable.d.ts) - Create a type that makes the given keys non-nullable.
 - [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
 - [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
@@ -247,6 +248,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`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))
+- [`IsTuple`](source/is-tuple.d.ts) - Returns a boolean for whether the given array is a tuple.
 
 ### JSON
 
@@ -367,6 +369,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `SetElement` - See [`IterableElement`](source/iterable-element.d.ts)
 - `SetEntry` - See [`IterableElement`](source/iterable-element.d.ts)
 - `SetValues` - See [`IterableElement`](source/iterable-element.d.ts)
+- `PickByTypes` - See [`ConditionalPick`](source/conditional-pick.d.ts)
 
 ## Tips
 
@@ -1048,6 +1051,7 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o
 
 - [Sindre Sorhus](https://github.com/sindresorhus)
 - [Haozheng Li](https://github.com/Emiyaaaaa)
+- [Som Shekhar Mukherjee](https://github.com/som-sm)
 - [Jarek Radosz](https://github.com/CvX)
 - [Dimitri Benin](https://github.com/BendingBender)
 - [Pelle Wessman](https://github.com/voxpelli)

package/source/internal/array.d.ts

@@ -1,3 +1,4 @@
+import type {IfNever} from '../if-never';
 import type {UnknownArray} from '../unknown-array';
 
 /**
@@ -90,4 +91,36 @@ T extends readonly [...infer U] ?
 /**
 Returns whether the given array `T` is readonly.
 */
-export type IsArrayReadonly<T extends UnknownArray> = T extends unknown[] ? false : true;
+export type IsArrayReadonly<T extends UnknownArray> = IfNever<T, false, T extends unknown[] ? false : true>;
+
+/**
+An if-else-like type that resolves depending on whether the given array is readonly.
+
+@see {@link IsArrayReadonly}
+
+@example
+```
+import type {ArrayTail} from 'type-fest';
+
+type ReadonlyPreservingArrayTail<TArray extends readonly unknown[]> =
+	ArrayTail<TArray> extends infer Tail
+		? IfArrayReadonly<TArray, Readonly<Tail>, Tail>
+		: never;
+
+type ReadonlyTail = ReadonlyPreservingArrayTail<readonly [string, number, boolean]>;
+//=> readonly [number, boolean]
+
+type NonReadonlyTail = ReadonlyPreservingArrayTail<[string, number, boolean]>;
+//=> [number, boolean]
+
+type ShouldBeTrue = IfArrayReadonly<readonly unknown[]>;
+//=> true
+
+type ShouldBeBar = IfArrayReadonly<unknown[], 'foo', 'bar'>;
+//=> 'bar'
+```
+*/
+export type IfArrayReadonly<T extends UnknownArray, TypeIfArrayReadonly = true, TypeIfNotArrayReadonly = false> =
+	IsArrayReadonly<T> extends infer Result
+		? Result extends true ? TypeIfArrayReadonly : TypeIfNotArrayReadonly
+		: never; // Should never happen

package/source/internal/object.d.ts

@@ -1,5 +1,6 @@
 import type {Simplify} from '../simplify';
 import type {UnknownArray} from '../unknown-array';
+import type {KeysOfUnion} from '../keys-of-union';
 import type {FilterDefinedKeys, FilterOptionalKeys} from './keys';
 import type {NonRecursiveType} from './type';
 import type {ToString} from './string';
@@ -80,3 +81,44 @@ export type UndefinedToOptional<T extends object> = Simplify<
 	[Key in keyof Pick<T, FilterOptionalKeys<T>>]?: Exclude<T[Key], undefined>;
 }
 >;
+
+/**
+Works similar to the built-in `Pick` utility type, except for the following differences:
+- Distributes over union types and allows picking keys from any member of the union type.
+- Primitives types are returned as-is.
+- Picks all keys if `Keys` is `any`.
+- Doesn't pick `number` from a `string` index signature.
+
+@example
+```
+type ImageUpload = {
+	url: string;
+	size: number;
+	thumbnailUrl: string;
+};
+
+type VideoUpload = {
+	url: string;
+	duration: number;
+	encodingFormat: string;
+};
+
+// Distributes over union types and allows picking keys from any member of the union type
+type MediaDisplay = HomomorphicPick<ImageUpload | VideoUpload, "url" | "size" | "duration">;
+//=> {url: string; size: number} | {url: string; duration: number}
+
+// Primitive types are returned as-is
+type Primitive = HomomorphicPick<string | number, 'toUpperCase' | 'toString'>;
+//=> string | number
+
+// Picks all keys if `Keys` is `any`
+type Any = HomomorphicPick<{a: 1; b: 2} | {c: 3}, any>;
+//=> {a: 1; b: 2} | {c: 3}
+
+// Doesn't pick `number` from a `string` index signature
+type IndexSignature = HomomorphicPick<{[k: string]: unknown}, number>;
+//=> {}
+*/
+export type HomomorphicPick<T, Keys extends KeysOfUnion<T>> = {
+	[P in keyof T as Extract<P, Keys>]: T[P]
+};

package/source/is-equal.d.ts

@@ -25,7 +25,7 @@ type Includes<Value extends readonly any[], Item> =
 @category Utilities
 */
 export type IsEqual<A, B> =
-	(<G>() => G extends A ? 1 : 2) extends
-	(<G>() => G extends B ? 1 : 2)
+	(<G>() => G extends A & G | G ? 1 : 2) extends
+	(<G>() => G extends B & G | G ? 1 : 2)
 		? true
 		: false;

package/source/is-tuple.d.ts

@@ -0,0 +1,78 @@
+import type {IfAny} from './if-any';
+import type {IfNever} from './if-never';
+import type {UnknownArray} from './unknown-array';
+
+/**
+@see {@link IsTuple}
+*/
+export type IsTupleOptions = {
+	/**
+	Consider only fixed length arrays as tuples.
+
+	- When set to `true` (default), arrays with rest elements (e.g., `[1, ...number[]]`) are _not_ considered as tuples.
+	- When set to `false`, arrays with at least one non-rest element (e.g., `[1, ...number[]]`) are considered as tuples.
+
+	@default true
+
+	@example
+	```ts
+	import type {IsTuple} from 'type-fest';
+
+	type Example1 = IsTuple<[number, ...number[]], {fixedLengthOnly: true}>;
+	//=> false
+
+	type Example2 = IsTuple<[number, ...number[]], {fixedLengthOnly: false}>;
+	//=> true
+	```
+	*/
+	fixedLengthOnly?: boolean;
+};
+
+/**
+Returns a boolean for whether the given array is a tuple.
+
+Use-case:
+- If you want to make a conditional branch based on the result of whether an array is a tuple or not.
+
+Note: `IsTuple` returns `boolean` when instantiated with a union of tuple and non-tuple (e.g., `IsTuple<[1, 2] | number[]>`).
+
+@example
+```ts
+import type {IsTuple} from 'type-fest';
+
+type Tuple = IsTuple<[1, 2, 3]>;
+//=> true
+
+type NotTuple = IsTuple<number[]>;
+//=> false
+
+type TupleWithOptionalItems = IsTuple<[1?, 2?]>;
+//=> true
+
+type RestItemsNotAllowed = IsTuple<[1, 2, ...number[]]>;
+//=> false
+
+type RestItemsAllowed = IsTuple<[1, 2, ...number[]], {fixedLengthOnly: false}>;
+//=> true
+```
+
+@see {@link IsTupleOptions}
+
+@category Type Guard
+@category Utilities
+*/
+export type IsTuple<
+	TArray extends UnknownArray,
+	Options extends IsTupleOptions = {fixedLengthOnly: true},
+> =
+	IfAny<TArray, boolean, IfNever<TArray, false,
+	TArray extends unknown // For distributing `TArray`
+		? number extends TArray['length']
+			? Options['fixedLengthOnly'] extends false
+				? IfNever<keyof TArray & `${number}`,
+				TArray extends readonly [...any, any] ? true : false, // To handle cases where a non-rest element follows a rest element, e.g., `[...number[], number]`
+				true>
+				: false
+			: true
+		: false
+	>>;

package/source/partial-deep.d.ts

@@ -1,7 +1,7 @@
 import type {BuiltIns} from './internal';
 
 /**
-@see PartialDeep
+@see {@link PartialDeep}
 */
 export type PartialDeepOptions = {
 	/**
@@ -10,6 +10,32 @@ export type PartialDeepOptions = {
 	@default false
 	*/
 	readonly recurseIntoArrays?: boolean;
+
+	/**
+	Allows `undefined` values in non-tuple arrays.
+
+	- When set to `true`, elements of non-tuple arrays can be `undefined`.
+	- When set to `false`, only explicitly defined elements are allowed in non-tuple arrays, ensuring stricter type checking.
+
+	@default true
+
+	@example
+	You can prevent `undefined` values in non-tuple arrays by passing `{recurseIntoArrays: true; allowUndefinedInNonTupleArrays: false}` as the second type argument:
+
+	```
+	import type {PartialDeep} from 'type-fest';
+
+	type Settings = {
+		languages: string[];
+	};
+
+	declare const partialSettings: PartialDeep<Settings, {recurseIntoArrays: true; allowUndefinedInNonTupleArrays: false}>;
+
+	partialSettings.languages = [undefined]; // Error
+	partialSettings.languages = []; // Ok
+	```
+	*/
+	readonly allowUndefinedInNonTupleArrays?: boolean;
 };
 
 /**
@@ -25,12 +51,12 @@ import type {PartialDeep} from 'type-fest';
 
 const settings: Settings = {
 	textEditor: {
-		fontSize: 14;
-		fontColor: '#000000';
-		fontWeight: 400;
-	}
-	autocomplete: false;
-	autosave: true;
+		fontSize: 14,
+		fontColor: '#000000',
+		fontWeight: 400
+	},
+	autocomplete: false,
+	autosave: true
 };
 
 const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
@@ -45,7 +71,7 @@ By default, this does not affect elements in array and tuple types. You can chan
 ```
 import type {PartialDeep} from 'type-fest';
 
-interface Settings {
+type Settings = {
 	languages: string[];
 }
 
@@ -54,6 +80,8 @@ const partialSettings: PartialDeep<Settings, {recurseIntoArrays: true}> = {
 };
 ```
 
+@see {@link PartialDeepOptions}
+
 @category Object
 @category Array
 @category Set
@@ -74,8 +102,8 @@ export type PartialDeep<T, Options extends PartialDeepOptions = {}> = T extends
 							? 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>>
+										? ReadonlyArray<PartialDeep<Options['allowUndefinedInNonTupleArrays'] extends false ? ItemType : ItemType | undefined, Options>>
+										: Array<PartialDeep<Options['allowUndefinedInNonTupleArrays'] extends false ? ItemType : 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>

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

@@ -1,6 +1,16 @@
-import type {Except} from './except';
 import type {Simplify} from './simplify';
 
+type SetFieldTypeOptions = {
+	/**
+	Preserve optional and readonly modifiers for properties being updated.
+
+	NOTE: Property modifiers will always be preserved for properties that are not being updated.
+
+	@default true
+	*/
+	preservePropertyModifiers?: boolean;
+};
+
 /**
 Create a type that changes the type of the given keys.
 
@@ -15,23 +25,33 @@ Use-cases:
 import type {SetFieldType} from 'type-fest';
 
 type MyModel = {
-	id: number;
-	createdAt: Date;
-	updatedAt: Date;
+	readonly id: number;
+	readonly createdAt: Date;
+	updatedAt?: Date;
 };
 
 type MyModelApi = SetFieldType<MyModel, 'createdAt' | 'updatedAt', string>;
 // {
-// 	id: number;
-// 	createdAt: string;
-// 	updatedAt: string;
+// 	readonly id: number;
+// 	readonly createdAt: string;
+// 	updatedAt?: string;
+// }
+
+// `preservePropertyModifiers` option can be set to `false` if you want to remove property modifiers for properties being updated
+type MyModelApi = SetFieldType<MyModel, 'createdAt' | 'updatedAt', string, {preservePropertyModifiers: false}>;
+// {
+// 	readonly id: number;
+// 	createdAt: string; // no longer readonly
+// 	updatedAt: string; // no longer optional
 // }
 ```
 
 @category Object
 */
-export type SetFieldType<BaseType, Keys extends keyof BaseType, NewType> =
-	Simplify<
-	Except<BaseType, Keys> &
-	Record<Keys, NewType>
-	>;
+export type SetFieldType<BaseType, Keys extends keyof BaseType, NewType, Options extends SetFieldTypeOptions = {preservePropertyModifiers: true}> =
+	Simplify<{
+		[P in keyof BaseType]: P extends Keys ? NewType : BaseType[P];
+	} & (
+		// `Record` is used to remove property modifiers
+		Options['preservePropertyModifiers'] extends false ? Record<Keys, NewType> : unknown
+	)>;

package/source/set-optional.d.ts

@@ -1,4 +1,6 @@
 import type {Except} from './except';
+import type {HomomorphicPick} from './internal';
+import type {KeysOfUnion} from './keys-of-union';
 import type {Simplify} from './simplify';
 
 /**
@@ -32,6 +34,6 @@ export type SetOptional<BaseType, Keys extends keyof BaseType> =
 		// Pick just the keys that are readonly from the base type.
 		Except<BaseType, Keys> &
 		// Pick the keys that should be mutable from the base type and make them mutable.
-		Partial<Except<BaseType, Exclude<keyof BaseType, Keys>>>
+		Partial<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
 		>
 		: never;

package/source/set-readonly.d.ts

@@ -1,4 +1,6 @@
 import type {Except} from './except';
+import type {HomomorphicPick} from './internal';
+import type {KeysOfUnion} from './keys-of-union';
 import type {Simplify} from './simplify';
 
 /**
@@ -33,6 +35,6 @@ export type SetReadonly<BaseType, Keys extends keyof BaseType> =
 	BaseType extends unknown
 		? Simplify<
 		Except<BaseType, Keys> &
-		Readonly<Except<BaseType, Exclude<keyof BaseType, Keys>>>
+		Readonly<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
 		>
 		: never;

package/source/set-required-deep.d.ts

@@ -0,0 +1,46 @@
+import type {NonRecursiveType, StringToNumber} from './internal';
+import type {Paths} from './paths';
+import type {SimplifyDeep} from './simplify-deep';
+import type {UnknownArray} from './unknown-array';
+
+/**
+Create a type that makes the given keys required. You can specify deeply nested key paths. The remaining keys are kept as is.
+
+Use-case: Selectively make nested properties required in complex types like models.
+
+@example
+```
+import type {SetRequiredDeep} from 'type-fest';
+
+type Foo = {
+	a?: number;
+	b?: string;
+	c?: {
+		d?: number
+	}[]
+}
+
+type SomeRequiredDeep = SetRequiredDeep<Foo, 'a' | `c.${number}.d`>;
+// type SomeRequiredDeep = {
+// 	a: number; // Is now required
+// 	b?: string;
+// 	c: {
+// 		d: number // Is now required
+// 	}[]
+// }
+```
+
+@category Object
+*/
+export type SetRequiredDeep<BaseType, KeyPaths extends Paths<BaseType>> =
+BaseType extends NonRecursiveType
+	? BaseType
+	: SimplifyDeep<(
+		BaseType extends UnknownArray
+			? {}
+			: {[K in keyof BaseType as K extends (KeyPaths | StringToNumber<KeyPaths & string>) ? K : never]-?: BaseType[K]}
+	) & {
+		[K in keyof BaseType]: Extract<KeyPaths, `${K & (string | number)}.${string}`> extends never
+			? BaseType[K]
+			: SetRequiredDeep<BaseType[K], KeyPaths extends `${K & (string | number)}.${infer Rest extends Paths<BaseType[K]>}` ? Rest : never>
+	}>;

package/source/set-required.d.ts

@@ -1,5 +1,9 @@
 import type {Except} from './except';
+import type {HomomorphicPick, IfArrayReadonly} from './internal';
+import type {KeysOfUnion} from './keys-of-union';
+import type {OptionalKeysOf} from './optional-keys-of';
 import type {Simplify} from './simplify';
+import type {UnknownArray} from './unknown-array';
 
 /**
 Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
@@ -22,19 +26,46 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // 	b: string; // Was already required and still is.
 // 	c: boolean; // Is now required.
 // }
+
+// Set specific indices in an array to be required.
+type ArrayExample = SetRequired<[number?, number?, number?], 0 | 1>;
+//=> [number, number, number?]
 ```
 
 @category Object
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType> =
-	// `extends unknown` is always going to be the case and is used to convert any
-	// union into a [distributive conditional
-	// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
-	BaseType extends unknown
-		? Simplify<
+	BaseType extends UnknownArray
+		? SetArrayRequired<BaseType, Keys> extends infer ResultantArray
+			? IfArrayReadonly<BaseType, Readonly<ResultantArray>, ResultantArray>
+			: never
+		: Simplify<
 		// Pick just the keys that are optional from the base type.
 		Except<BaseType, Keys> &
 		// Pick the keys that should be required from the base type and make them required.
-		Required<Except<BaseType, Exclude<keyof BaseType, Keys>>>
-		>
-		: never;
+		Required<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
+		>;
+
+/**
+Remove the optional modifier from the specified keys in an array.
+*/
+type SetArrayRequired<
+	TArray extends UnknownArray,
+	Keys,
+	Counter extends any[] = [],
+	Accumulator extends UnknownArray = [],
+> = TArray extends unknown // For distributing `TArray` when it's a union
+	? keyof TArray & `${number}` extends never
+		// Exit if `TArray` is empty (e.g., []), or
+		// `TArray` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`).
+		? [...Accumulator, ...TArray]
+		: TArray extends readonly [(infer First)?, ...infer Rest]
+			? '0' extends OptionalKeysOf<TArray> // If the first element of `TArray` is optional
+				? `${Counter['length']}` extends `${Keys & (string | number)}` // If the current index needs to be required
+					? SetArrayRequired<Rest, Keys, [...Counter, any], [...Accumulator, First]>
+					// If the current element is optional, but it doesn't need to be required,
+					// then we can exit early, since no further elements can now be made required.
+					: [...Accumulator, ...TArray]
+				: SetArrayRequired<Rest, Keys, [...Counter, any], [...Accumulator, TArray[0]]>
+			: never // Should never happen, since `[(infer F)?, ...infer R]` is a top-type for arrays.
+	: never; // Should never happen