type-fest 2.17.0 → 2.19.0

package/index.d.ts

@@ -15,6 +15,7 @@ export {RequireExactlyOne} from './source/require-exactly-one';
 export {RequireAllOrNone} from './source/require-all-or-none';
 export {RemoveIndexSignature} from './source/remove-index-signature';
 export {PartialDeep, PartialDeepOptions} from './source/partial-deep';
+export {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './source/partial-on-undefined-deep';
 export {ReadonlyDeep} from './source/readonly-deep';
 export {LiteralUnion} from './source/literal-union';
 export {Promisable} from './source/promisable';
@@ -22,6 +23,7 @@ export {Opaque, UnwrapOpaque} from './source/opaque';
 export {InvariantOf} from './source/invariant-of';
 export {SetOptional} from './source/set-optional';
 export {SetRequired} from './source/set-required';
+export {SetNonNullable} from './source/set-non-nullable';
 export {ValueOf} from './source/value-of';
 export {PromiseValue} from './source/promise-value';
 export {AsyncReturnType} from './source/async-return-type';
@@ -61,6 +63,7 @@ export {OptionalKeysOf} from './source/optional-keys-of';
 export {HasOptionalKeys} from './source/has-optional-keys';
 export {RequiredKeysOf} from './source/required-keys-of';
 export {HasRequiredKeys} from './source/has-required-keys';
+export {Spread} from './source/spread';
 
 // Template literal types
 export {CamelCase} from './source/camel-case';

package/package.json

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

package/readme.md

@@ -40,41 +40,6 @@
 			<br>
 			<br>
 			<br>
-			<a href="https://neverinstall.com/spaces/devtools?utm_source=github&utm_medium=sponsor&utm_campaign=sindre#gh-light-mode-only">
-				<div>
-					<img src="https://sindresorhus.com/assets/thanks/neverinstall-logo-light.svg" width="200" alt="neverinstall">
-				</div>
-				<br>
-				<b>All your favourite IDE's now available on the cloud</b>
-				<div>
-					<sub>
-					Neverinstall gives you an uninterrupted development experience and improved accessibility,
-					<br>
-					allowing you to code faster, better and on-the-go on your favourite IDEs like
-					<br>
-					Android Studio, VS Code, Jupyter and PyCharm using your browser.
-					</sub>
-				</div>
-			</a>
-			<a href="https://neverinstall.com/spaces/devtools?utm_source=github&utm_medium=sponsor&utm_campaign=sindre#gh-dark-mode-only">
-				<div>
-					<img src="https://sindresorhus.com/assets/thanks/neverinstall-logo-dark.svg" width="200" alt="neverinstall">
-				</div>
-				<br>
-				<b>All your favourite IDE's now available on the cloud</b>
-				<div>
-					<sub>
-					Neverinstall gives you an uninterrupted development experience and improved accessibility,
-					<br>
-					allowing you to code faster, better and on-the-go on your favourite IDEs like
-					<br>
-					Android Studio, VS Code, Jupyter and PyCharm using your browser.
-					</sub>
-				</div>
-			</a>
-			<br>
-			<br>
-			<br>
 			<a href="https://www.useanvil.com/?utm_source=sindresorhus#gh-light-mode-only">
 				<div>
 					<img src="https://sindresorhus.com/assets/thanks/anvil-logo-light.svg" width="200" alt="Anvil">
@@ -169,6 +134,7 @@ Click the type names for complete docs.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.
 - [`RemoveIndexSignature`](source/remove-index-signature.d.ts) - Create a type that only has explicitly defined properties, absent of any index signatures.
 - [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
+- [`PartialOnUndefinedDeep`](source/partial-on-undefined-deep.d.ts) - Create a deep version of another type where all keys accepting `undefined` type are set to optional.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
 - [`LiteralUnion`](source/literal-union.d.ts) - 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. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
 - [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
@@ -176,6 +142,7 @@ Click the type names for complete docs.
 - [`InvariantOf`](source/invariant-of.d.ts) - Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
+- [`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.
 - [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
@@ -196,6 +163,7 @@ Click the type names for complete docs.
 - [`HasOptionalKeys`](source/has-optional-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any optional fields.
 - [`RequiredKeysOf`](source/required-keys-of.d.ts) - Extract all required keys from the given type.
 - [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
+- [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
 
 ### JSON
 

package/source/exact.d.ts

@@ -1,6 +1,29 @@
-import type {Primitive} from './primitive';
 import type {KeysOfUnion} from './internal';
 
+/**
+Extract the element of an array that also works for array union.
+
+Returns `never` if T is not an array.
+
+It creates a type-safe way to access the element type of `unknown` type.
+*/
+type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never;
+
+/**
+Extract the object field type if T is an object and K is a key of T, return `never` otherwise.
+
+It creates a type-safe way to access the member type of `unknown` type.
+*/
+type ObjectValue<T, K> = K extends keyof T ? T[K] : never;
+
+/**
+Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.
+- Generate a list of keys that exists in `InputType` but not in `ParameterType`.
+- Mark these excess keys as `never`.
+*/
+type ExactObject<ParameterType, InputType> = {[Key in keyof ParameterType]: Exact<ParameterType[Key], ObjectValue<InputType, Key>>}
+	& Record<Exclude<keyof InputType, KeysOfUnion<ParameterType>>, never>;
+
 /**
 Create a type that does not allow extra properties, meaning it only allows properties that are explicitly declared.
 
@@ -41,11 +64,10 @@ onlyAcceptNameImproved(invalidInput); // Compilation error
 
 @category Utilities
 */
-export type Exact<ParameterType, InputType extends ParameterType> = ParameterType extends Primitive
-	? ParameterType
-	/*
-	Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.
-	- Generate a list of keys that exists in `InputType` but not in `ParameterType`.
-	- Mark these excess keys as `never`.
-	*/
-	: {[Key in keyof ParameterType]: Exact<ParameterType[Key], InputType[Key]>} & Record<Exclude<keyof InputType, KeysOfUnion<ParameterType>>, never>;
+export type Exact<ParameterType, InputType> =
+	// Convert union of array to array of union: A[] & B[] => (A & B)[]
+	ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
+	// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
+	: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
+	: ParameterType extends object ? ExactObject<ParameterType, InputType>
+	: ParameterType;

package/source/jsonify.d.ts

@@ -67,25 +67,24 @@ type Jsonify<T> =
 	// Note: The use of tuples in this first condition side-steps distributive conditional types
 	// (see https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532)
 	[Extract<T, NotJsonable | bigint>] extends [never]
-		? T extends PositiveInfinity | NegativeInfinity ? null
-		: T extends JsonPrimitive
-			? T // Primitive is acceptable
-			: T extends Number ? number
-			: T extends String ? string
-			: T extends Boolean ? boolean
-			: T extends Map<any, any> | Set<any> ? {}
-			: T extends TypedArray ? Record<string, number>
-			: T extends Array<infer U>
-				? Array<Jsonify<U extends NotJsonable ? null : U>> // It's an array: recursive call for its children
-				: T extends object
-					? T extends {toJSON(): infer J}
-						? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?
-							? J // Then T is Jsonable and its Jsonable value is J
-							: never // Not Jsonable because its toJSON() method does not return JsonValue
-						: {[P in keyof T as P extends symbol
-							? never
-							: T[P] extends NotJsonable
-							? never
-							: P]: Jsonify<Required<T>[P]>} // It's an object: recursive call for its children
-					: never // Otherwise any other non-object is removed
+		? T extends PositiveInfinity | NegativeInfinity	? null
+			: T extends JsonPrimitive ? T // Primitive is acceptable
+			: T extends object
+				// 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
+					: never // Not Jsonable because its toJSON() method does not return JsonValue
+				// Instanced primitives are objects
+				: T extends Number ? number
+				: T extends String ? string
+				: T extends Boolean ? boolean
+				: T extends Map<any, any> | Set<any> ? {}
+				: T extends TypedArray ? Record<string, number>
+				: T extends any[]
+					? {[I in keyof T]: T[I] extends NotJsonable ? null : Jsonify<T[I]>}
+				: {[P in keyof T as P extends symbol ? never
+					: T[P] extends NotJsonable ? never
+					: P
+				]: Jsonify<Required<T>[P]>} // Recursive call for its children
+			: never // Otherwise any other non-object is removed
 		: never; // Otherwise non-JSONable type union was found not empty

package/source/package-json.d.ts

@@ -223,15 +223,17 @@ declare namespace PackageJson {
 		string
 	>;
 
+	type ExportConditions = {[condition in ExportCondition]: Exports};
+
 	/**
 	Entry points of a module, optionally with conditions and subpath exports.
 	*/
 	export type Exports =
 	| null
 	| string
-	| string[]
-	| {[key in ExportCondition]: Exports}
-	| {[key: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
+	| Array<string | ExportConditions>
+	| ExportConditions
+	| {[path: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
 
 	/**
 	Import map entries of a module, optionally with conditions.

package/source/partial-on-undefined-deep.d.ts

@@ -0,0 +1,70 @@
+import type {BuiltIns} from './internal';
+import type {Merge} from './merge';
+
+/**
+@see PartialOnUndefinedDeep
+*/
+export interface PartialOnUndefinedDeepOptions {
+	/**
+	Whether to affect the individual elements of arrays and tuples.
+
+	@default false
+	*/
+	readonly recurseIntoArrays?: boolean;
+}
+
+/**
+Create a deep version of another type where all keys accepting `undefined` type are set to optional.
+
+This utility type is recursive, transforming at any level deep. By default, it does not affect arrays and tuples items unless you explicitly pass `{recurseIntoArrays: true}` as the second type argument.
+
+Use-cases:
+- Make all properties of a type that can be undefined optional to not have to specify keys with undefined value.
+
+@example
+```
+import type {PartialOnUndefinedDeep} from 'type-fest';
+
+interface Settings {
+	optionA: string;
+	optionB: number | undefined;
+	subOption: {
+		subOptionA: boolean;
+		subOptionB: boolean | undefined;
+	}
+};
+
+const testSettings: PartialOnUndefinedDeep<Settings> = {
+	optionA: 'foo',
+	// 👉 optionB is now optional and can be omitted
+	subOption: {
+		subOptionA: true,
+		// 👉 subOptionB is now optional as well and can be omitted
+	},
+};
+```
+
+@category Object
+*/
+export type PartialOnUndefinedDeep<T, Options extends PartialOnUndefinedDeepOptions = {}> = T extends Record<any, any> | undefined
+	? {[KeyType in keyof T as undefined extends T[KeyType] ? KeyType : never]?: PartialOnUndefinedDeepValue<T[KeyType], Options>} extends infer U // Make a partial type with all value types accepting undefined (and set them optional)
+		? Merge<{[KeyType in keyof T as KeyType extends keyof U ? never : KeyType]: PartialOnUndefinedDeepValue<T[KeyType], Options>}, U> // Join all remaining keys not treated in U
+		: never // Should not happen
+	: T;
+
+/**
+Utility type to get the value type by key and recursively call `PartialOnUndefinedDeep` to transform sub-objects.
+*/
+type PartialOnUndefinedDeepValue<T, Options extends PartialOnUndefinedDeepOptions> = T extends BuiltIns | ((...arguments: any[]) => unknown)
+	? T
+	: T extends ReadonlyArray<infer U> // Test if type is array or tuple
+	? Options['recurseIntoArrays'] extends true // Check if option is activated
+		? U[] extends T // Check if array not tuple
+		? readonly U[] extends T
+			? ReadonlyArray<PartialOnUndefinedDeep<U, Options>> // Readonly array treatment
+			: Array<PartialOnUndefinedDeep<U, Options>> // Mutable array treatment
+		: PartialOnUndefinedDeep<{[Key in keyof T]: PartialOnUndefinedDeep<T[Key], Options>}, Options> // Tuple treatment
+		: T
+	: T extends Record<any, any> | undefined
+	? PartialOnUndefinedDeep<T, Options>
+	: unknown;

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

@@ -0,0 +1,35 @@
+import type {Except} from './except';
+import type {Simplify} from './simplify';
+
+/**
+Create a type that makes the given keys non-nullable. The remaining keys are kept as is.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are non-nullable.
+
+@example
+```
+import type {SetNonNullable} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string | undefined;
+	c?: boolean | null;
+}
+
+type SomeNonNullable = SetNonNullable<Foo, 'b' | 'c'>;
+// type SomeNonNullable = {
+// 	a: number;
+// 	b: string; // Can no longer be undefined.
+// 	c?: boolean; // Can no longer be null, but is still optional.
+// }
+```
+
+@category Object
+*/
+export type SetNonNullable<BaseType, Keys extends keyof BaseType> =
+	Simplify<
+		// Pick just the keys that are readonly from the base type.
+		Except<BaseType, Keys> &
+		// Pick the keys that should be non-nullable from the base type and make them non-nullable.
+		{[Key in Keys]: NonNullable<BaseType[Key]>}
+	>;

package/source/spread.d.ts

@@ -0,0 +1,85 @@
+import type {Except} from './except';
+import type {RequiredKeysOf} from './required-keys-of';
+import type {Simplify} from './simplify';
+
+type SpreadObject<FirstType extends object, SecondType extends object> = {
+	[Key in keyof FirstType]: Key extends keyof SecondType
+		? FirstType[Key] | Required<SecondType>[Key]
+		: FirstType[Key];
+} & Pick<
+	SecondType,
+	RequiredKeysOf<SecondType> | Exclude<keyof SecondType, keyof FirstType>
+>;
+
+type TupleOrArray = readonly [...unknown[]];
+
+type SpreadTupleOrArray<
+	FirstType extends TupleOrArray,
+	SecondType extends TupleOrArray,
+> = Array<FirstType[number] | SecondType[number]>;
+
+type Spreadable = object | TupleOrArray;
+
+/**
+Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
+
+@example
+```
+import type {Spread} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b?: string;
+};
+
+type Bar = {
+	b?: number;
+	c: boolean;
+};
+
+const foo = {a: 1, b: '2'};
+const bar = {c: false};
+const fooBar = {...foo, ...bar};
+
+type FooBar = Spread<Foo, Bar>;
+// type FooBar = {
+// 	a: number;
+// 	b?: string | number | undefined;
+// 	c: boolean;
+// }
+
+const baz = (argument: FooBar) => {
+	// Do something
+}
+
+baz(fooBar);
+```
+
+@example
+```
+import type {Spread} from 'type-fest';
+
+const foo = [1, 2, 3];
+const bar = ['4', '5', '6'];
+
+const fooBar = [...foo, ...bar];
+type FooBar = Spread<typeof foo, typeof bar>;
+// FooBar = (string | number)[]
+
+const baz = (argument: FooBar) => {
+	// Do something
+};
+
+baz(fooBar);
+```
+
+@category Object
+*/
+export type Spread<
+    FirstType extends Spreadable,
+    SecondType extends Spreadable,
+> = FirstType extends TupleOrArray
+	? SecondType extends TupleOrArray
+		? SpreadTupleOrArray<FirstType, SecondType>
+		: Simplify<SpreadObject<FirstType, SecondType>>
+	: Simplify<SpreadObject<FirstType, SecondType>>;