type-fest 0.15.0 → 0.18.0

package/index.d.ts

@@ -24,6 +24,11 @@ export {ConditionalPick} from './source/conditional-pick';
 export {UnionToIntersection} from './source/union-to-intersection';
 export {Stringified} from './source/stringified';
 export {FixedLengthArray} from './source/fixed-length-array';
+export {IterableElement} from './source/iterable-element';
+export {Entry} from './source/entry';
+export {Entries} from './source/entries';
+export {SetReturnType} from './source/set-return-type';
+export {Asyncify} from './source/asyncify';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.15.0",
+	"version": "0.18.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -32,7 +32,7 @@
 		"json"
 	],
 	"devDependencies": {
-		"tsd": "^0.11.0",
+		"tsd": "^0.13.1",
 		"xo": "^0.28.2"
 	},
 	"types": "index.d.ts",

package/readme.md

@@ -83,6 +83,11 @@ Click the type names for complete docs.
 - [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
 - [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
 - [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
+- [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
+- [`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.
+- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.
 
 ### Miscellaneous
 

package/source/asyncify.d.ts

@@ -0,0 +1,31 @@
+import {PromiseValue} from './promise-value';
+import {SetReturnType} from './set-return-type';
+
+/**
+Create an async version of the given function type, by boxing the return type in `Promise` while keeping the same parameter types.
+
+Use-case: You have two functions, one synchronous and one asynchronous that do the same thing. Instead of having to duplicate the type definition, you can use `Asyncify` to reuse the synchronous type.
+
+@example
+```
+import {Asyncify} from 'type-fest';
+
+// Synchronous function.
+function getFooSync(someArg: SomeType): Foo {
+	// …
+}
+
+type AsyncifiedFooGetter = Asyncify<typeof getFooSync>;
+//=> type AsyncifiedFooGetter = (someArg: SomeType) => Promise<Foo>;
+
+// Same as `getFooSync` but asynchronous.
+const getFooAsync: AsyncifiedFooGetter = (someArg) => {
+	// TypeScript now knows that `someArg` is `SomeType` automatically.
+	// It also knows that this function must return `Promise<Foo>`.
+	// If you have `@typescript-eslint/promise-function-async` linter rule enabled, it will even report that "Functions that return promises must be async.".
+
+	// …
+}
+```
+*/
+export type Asyncify<Fn extends (...args: any[]) => any> = SetReturnType<Fn, Promise<PromiseValue<ReturnType<Fn>>>>;

package/source/entries.d.ts

@@ -0,0 +1,57 @@
+import {ArrayEntry, MapEntry, ObjectEntry, SetEntry} from './entry';
+
+type ArrayEntries<BaseType extends readonly unknown[]> = Array<ArrayEntry<BaseType>>;
+type MapEntries<BaseType> = Array<MapEntry<BaseType>>;
+type ObjectEntries<BaseType> = Array<ObjectEntry<BaseType>>;
+type SetEntries<BaseType extends Set<unknown>> = Array<SetEntry<BaseType>>;
+
+/**
+Many collections have an `entries` method which returns an array of a given object's own enumerable string-keyed property [key, value] pairs. The `Entries` type will return the type of that collection's entries.
+
+For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries|`Object`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries|`Map`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries|`Array`}, and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries|`Set`} collections all have this method. Note that `WeakMap` and `WeakSet` do not have this method since their entries are not enumerable.
+
+@see `Entry` if you want to just access the type of a single entry.
+
+@example
+```
+import {Entries} from 'type-fest';
+
+interface Example {
+	someKey: number;
+}
+
+const manipulatesEntries = (examples: Entries<Example>) => examples.map(example => [
+	// Does some arbitrary processing on the key (with type information available)
+	example[0].toUpperCase(),
+
+	// Does some arbitrary processing on the value (with type information available)
+	example[1].toFixed()
+]);
+
+const example: Example = {someKey: 1};
+const entries = Object.entries(example) as Entries<Example>;
+const output = manipulatesEntries(entries);
+
+// Objects
+const objectExample = {a: 1};
+const objectEntries: Entries<typeof objectExample> = [['a', 1]];
+
+// Arrays
+const arrayExample = ['a', 1];
+const arrayEntries: Entries<typeof arrayExample> = [[0, 'a'], [1, 1]];
+
+// Maps
+const mapExample = new Map([['a', 1]]);
+const mapEntries: Entries<typeof map> = [['a', 1]];
+
+// Sets
+const setExample = new Set(['a', 1]);
+const setEntries: Entries<typeof setExample> = [['a', 'a'], [1, 1]];
+```
+*/
+export type Entries<BaseType> =
+	BaseType extends Map<unknown, unknown> ? MapEntries<BaseType>
+		: BaseType extends Set<unknown> ? SetEntries<BaseType>
+		: BaseType extends unknown[] ? ArrayEntries<BaseType>
+		: BaseType extends object ? ObjectEntries<BaseType>
+		: never;

package/source/entry.d.ts

@@ -0,0 +1,60 @@
+type MapKey<BaseType> = BaseType extends Map<infer KeyType, unknown> ? KeyType : never;
+type MapValue<BaseType> = BaseType extends Map<unknown, infer ValueType> ? ValueType : never;
+
+type ArrayEntry<BaseType extends readonly unknown[]> = [number, BaseType[number]];
+type MapEntry<BaseType> = [MapKey<BaseType>, MapValue<BaseType>];
+type ObjectEntry<BaseType> = [keyof BaseType, BaseType[keyof BaseType]];
+type SetEntry<BaseType> = BaseType extends Set<infer ItemType> ? [ItemType, ItemType] : never;
+
+/**
+Many collections have an `entries` method which returns an array of a given object's own enumerable string-keyed property [key, value] pairs. The `Entry` type will return the type of that collection's entry.
+
+For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries|`Object`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries|`Map`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries|`Array`}, and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries|`Set`} collections all have this method. Note that `WeakMap` and `WeakSet` do not have this method since their entries are not enumerable.
+
+@see `Entries` if you want to just access the type of the array of entries (which is the return of the `.entries()` method).
+
+@example
+```
+import {Entry} from 'type-fest';
+
+interface Example {
+	someKey: number;
+}
+
+const manipulatesEntry = (example: Entry<Example>) => [
+	// Does some arbitrary processing on the key (with type information available)
+	example[0].toUpperCase(),
+
+	// Does some arbitrary processing on the value (with type information available)
+	example[1].toFixed(),
+];
+
+const example: Example = {someKey: 1};
+const entry = Object.entries(example)[0] as Entry<Example>;
+const output = manipulatesEntry(entry);
+
+// Objects
+const objectExample = {a: 1};
+const objectEntry: Entry<typeof objectExample> = ['a', 1];
+
+// Arrays
+const arrayExample = ['a', 1];
+const arrayEntryString: Entry<typeof arrayExample> = [0, 'a'];
+const arrayEntryNumber: Entry<typeof arrayExample> = [1, 1];
+
+// Maps
+const mapExample = new Map([['a', 1]]);
+const mapEntry: Entry<typeof map> = ['a', 1];
+
+// Sets
+const setExample = new Set(['a', 1]);
+const setEntryString: Entry<typeof setExample> = ['a', 'a'];
+const setEntryNumber: Entry<typeof setExample> = [1, 1];
+```
+*/
+export type Entry<BaseType> =
+	BaseType extends Map<unknown, unknown> ? MapEntry<BaseType>
+		: BaseType extends Set<unknown> ? SetEntry<BaseType>
+		: BaseType extends unknown[] ? ArrayEntry<BaseType>
+		: BaseType extends object ? ObjectEntry<BaseType>
+		: never;

package/source/iterable-element.d.ts

@@ -0,0 +1,46 @@
+/**
+Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
+
+This can be useful, for example, if you want to get the type that is yielded in a generator function. Often the return type of those functions are not specified.
+
+This type works with both `Iterable`s and `AsyncIterable`s, so it can be use with synchronous and asynchronous generators.
+
+Here is an example of `IterableElement` in action with a generator function:
+
+@example
+```
+function * iAmGenerator() {
+	yield 1;
+	yield 2;
+}
+
+type MeNumber = IterableElement<ReturnType<typeof iAmGenerator>>
+```
+
+And here is an example with an async generator:
+
+@example
+```
+async function * iAmGeneratorAsync() {
+	yield 'hi';
+	yield true;
+}
+
+type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>
+```
+
+Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces. For example, `Array`, `Set`, `Map`, `stream.Readable`, etc.
+
+An example with an array of strings:
+
+@example
+```
+type MeString = IterableElement<string[]>
+```
+*/
+export type IterableElement<TargetIterable> =
+	TargetIterable extends Iterable<infer ElementType> ?
+	ElementType :
+	TargetIterable extends AsyncIterable<infer ElementType> ?
+	ElementType :
+	never;

package/source/literal-union.d.ts

@@ -28,6 +28,6 @@ const pet: Pet2 = '';
 ```
  */
 export type LiteralUnion<
-	LiteralType extends BaseType,
+	LiteralType,
 	BaseType extends Primitive
 > = LiteralType | (BaseType & {_?: never});

package/source/package-json.d.ts

@@ -1,4 +1,4 @@
-import {LiteralUnion} from '..';
+import {LiteralUnion} from './literal-union';
 
 declare namespace PackageJson {
 	/**
@@ -337,194 +337,193 @@ declare namespace PackageJson {
 		*/
 		jspm?: PackageJson;
 	}
-}
-
-/**
-Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
-*/
-export type PackageJson = {
-	/**
-	The name of the package.
-	*/
-	name?: string;
-
-	/**
-	Package version, parseable by [`node-semver`](https://github.com/npm/node-semver).
-	*/
-	version?: string;
 
 	/**
-	Package description, listed in `npm search`.
+	Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Containing standard npm properties.
 	*/
-	description?: string;
+	export interface PackageJsonStandard {
+		/**
+		The name of the package.
+		*/
+		name?: string;
 
-	/**
-	Keywords associated with package, listed in `npm search`.
-	*/
-	keywords?: string[];
+		/**
+		Package version, parseable by [`node-semver`](https://github.com/npm/node-semver).
+		*/
+		version?: string;
 
-	/**
-	The URL to the package's homepage.
-	*/
-	homepage?: LiteralUnion<'.', string>;
+		/**
+		Package description, listed in `npm search`.
+		*/
+		description?: string;
 
-	/**
-	The URL to the package's issue tracker and/or the email address to which issues should be reported.
-	*/
-	bugs?: PackageJson.BugsLocation;
+		/**
+		Keywords associated with package, listed in `npm search`.
+		*/
+		keywords?: string[];
 
-	/**
-	The license for the package.
-	*/
-	license?: string;
+		/**
+		The URL to the package's homepage.
+		*/
+		homepage?: LiteralUnion<'.', string>;
 
-	/**
-	The licenses for the package.
-	*/
-	licenses?: Array<{
-		type?: string;
-		url?: string;
-	}>;
+		/**
+		The URL to the package's issue tracker and/or the email address to which issues should be reported.
+		*/
+		bugs?: BugsLocation;
 
-	author?: PackageJson.Person;
+		/**
+		The license for the package.
+		*/
+		license?: string;
 
-	/**
-	A list of people who contributed to the package.
-	*/
-	contributors?: PackageJson.Person[];
+		/**
+		The licenses for the package.
+		*/
+		licenses?: Array<{
+			type?: string;
+			url?: string;
+		}>;
 
-	/**
-	A list of people who maintain the package.
-	*/
-	maintainers?: PackageJson.Person[];
+		author?: Person;
 
-	/**
-	The files included in the package.
-	*/
-	files?: string[];
+		/**
+		A list of people who contributed to the package.
+		*/
+		contributors?: Person[];
 
-	/**
-	Resolution algorithm for importing ".js" files from the package's scope.
+		/**
+		A list of people who maintain the package.
+		*/
+		maintainers?: Person[];
 
-	[Read more.](https://nodejs.org/api/esm.html#esm_package_json_type_field)
-	*/
-	type?: 'module' | 'commonjs';
+		/**
+		The files included in the package.
+		*/
+		files?: string[];
 
-	/**
-	The module ID that is the primary entry point to the program.
-	*/
-	main?: string;
+		/**
+		Resolution algorithm for importing ".js" files from the package's scope.
 
-	/**
-	Standard entry points of the package, with enhanced support for ECMAScript Modules.
+		[Read more.](https://nodejs.org/api/esm.html#esm_package_json_type_field)
+		*/
+		type?: 'module' | 'commonjs';
 
-	[Read more.](https://nodejs.org/api/esm.html#esm_package_entry_points)
-	*/
-	exports?: PackageJson.Exports;
+		/**
+		The module ID that is the primary entry point to the program.
+		*/
+		main?: string;
 
-	/**
-	The executable files that should be installed into the `PATH`.
-	*/
-	bin?:
-	| string
-	| {
-		[binary: string]: string;
-	};
+		/**
+		Standard entry points of the package, with enhanced support for ECMAScript Modules.
 
-	/**
-	Filenames to put in place for the `man` program to find.
-	*/
-	man?: string | string[];
+		[Read more.](https://nodejs.org/api/esm.html#esm_package_entry_points)
+		*/
+		exports?: Exports;
 
-	/**
-	Indicates the structure of the package.
-	*/
-	directories?: PackageJson.DirectoryLocations;
+		/**
+		The executable files that should be installed into the `PATH`.
+		*/
+		bin?:
+		| string
+		| {
+			[binary: string]: string;
+		};
 
-	/**
-	Location for the code repository.
-	*/
-	repository?:
-	| string
-	| {
-		type: string;
-		url: string;
+		/**
+		Filenames to put in place for the `man` program to find.
+		*/
+		man?: string | string[];
 
 		/**
-		Relative path to package.json if it is placed in non-root directory (for example if it is part of a monorepo).
+		Indicates the structure of the package.
+		*/
+		directories?: DirectoryLocations;
 
-		[Read more.](https://github.com/npm/rfcs/blob/latest/implemented/0010-monorepo-subdirectory-declaration.md)
+		/**
+		Location for the code repository.
 		*/
-		directory?: string;
-	};
+		repository?:
+		| string
+		| {
+			type: string;
+			url: string;
 
-	/**
-	Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point.
-	*/
-	scripts?: PackageJson.Scripts;
+			/**
+			Relative path to package.json if it is placed in non-root directory (for example if it is part of a monorepo).
 
-	/**
-	Is used to set configuration parameters used in package scripts that persist across upgrades.
-	*/
-	config?: {
-		[configKey: string]: unknown;
-	};
+			[Read more.](https://github.com/npm/rfcs/blob/latest/implemented/0010-monorepo-subdirectory-declaration.md)
+			*/
+			directory?: string;
+		};
 
-	/**
-	The dependencies of the package.
-	*/
-	dependencies?: PackageJson.Dependency;
+		/**
+		Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point.
+		*/
+		scripts?: Scripts;
 
-	/**
-	Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling.
-	*/
-	devDependencies?: PackageJson.Dependency;
+		/**
+		Is used to set configuration parameters used in package scripts that persist across upgrades.
+		*/
+		config?: {
+			[configKey: string]: unknown;
+		};
 
-	/**
-	Dependencies that are skipped if they fail to install.
-	*/
-	optionalDependencies?: PackageJson.Dependency;
+		/**
+		The dependencies of the package.
+		*/
+		dependencies?: Dependency;
 
-	/**
-	Dependencies that will usually be required by the package user directly or via another dependency.
-	*/
-	peerDependencies?: PackageJson.Dependency;
+		/**
+		Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling.
+		*/
+		devDependencies?: Dependency;
 
-	/**
-	Indicate peer dependencies that are optional.
-	*/
-	peerDependenciesMeta?: {
-		[packageName: string]: {
-			optional: true;
+		/**
+		Dependencies that are skipped if they fail to install.
+		*/
+		optionalDependencies?: Dependency;
+
+		/**
+		Dependencies that will usually be required by the package user directly or via another dependency.
+		*/
+		peerDependencies?: Dependency;
+
+		/**
+		Indicate peer dependencies that are optional.
+		*/
+		peerDependenciesMeta?: {
+			[packageName: string]: {
+				optional: true;
+			};
 		};
-	};
 
-	/**
-	Package names that are bundled when the package is published.
-	*/
-	bundledDependencies?: string[];
+		/**
+		Package names that are bundled when the package is published.
+		*/
+		bundledDependencies?: string[];
 
-	/**
-	Alias of `bundledDependencies`.
-	*/
-	bundleDependencies?: string[];
+		/**
+		Alias of `bundledDependencies`.
+		*/
+		bundleDependencies?: string[];
 
-	/**
-	Engines that this package runs on.
-	*/
-	engines?: {
-		[EngineName in 'npm' | 'node' | string]: string;
-	};
+		/**
+		Engines that this package runs on.
+		*/
+		engines?: {
+			[EngineName in 'npm' | 'node' | string]: string;
+		};
 
-	/**
-	@deprecated
-	*/
-	engineStrict?: boolean;
+		/**
+		@deprecated
+		*/
+		engineStrict?: boolean;
 
-	/**
-	Operating systems the module runs on.
-	*/
-	os?: Array<LiteralUnion<
+		/**
+		Operating systems the module runs on.
+		*/
+		os?: Array<LiteralUnion<
 		| 'aix'
 		| 'darwin'
 		| 'freebsd'
@@ -540,12 +539,12 @@ export type PackageJson = {
 		| '!sunos'
 		| '!win32',
 		string
-	>>;
+		>>;
 
-	/**
-	CPU architectures the module runs on.
-	*/
-	cpu?: Array<LiteralUnion<
+		/**
+		CPU architectures the module runs on.
+		*/
+		cpu?: Array<LiteralUnion<
 		| 'arm'
 		| 'arm64'
 		| 'ia32'
@@ -569,37 +568,37 @@ export type PackageJson = {
 		| '!x32'
 		| '!x64',
 		string
-	>>;
+		>>;
 
-	/**
-	If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.
-
-	@deprecated
-	*/
-	preferGlobal?: boolean;
+		/**
+		If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.
 
-	/**
-	If set to `true`, then npm will refuse to publish it.
-	*/
-	private?: boolean;
+		@deprecated
+		*/
+		preferGlobal?: boolean;
 
-	/**
-	A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
-	*/
-	publishConfig?: {
-		[config: string]: unknown;
-	};
+		/**
+		If set to `true`, then npm will refuse to publish it.
+		*/
+		private?: boolean;
 
-	/**
-	Describes and notifies consumers of a package's monetary support information.
+		/**
+		A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
+		*/
+		publishConfig?: {
+			[config: string]: unknown;
+		};
 
-	[Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md)
-	*/
-	funding?: string | {
 		/**
-		The type of funding.
+		Describes and notifies consumers of a package's monetary support information.
+
+		[Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md)
 		*/
-		type?: LiteralUnion<
+		funding?: string | {
+			/**
+			The type of funding.
+			*/
+			type?: LiteralUnion<
 			| 'github'
 			| 'opencollective'
 			| 'patreon'
@@ -607,16 +606,22 @@ export type PackageJson = {
 			| 'foundation'
 			| 'corporation',
 			string
-		>;
-		/**
-		The URL to the funding page.
-		*/
-		url: string;
-	};
-} &
+			>;
+
+			/**
+			The URL to the funding page.
+			*/
+			url: string;
+		};
+	}
+}
+
+/**
+Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
+*/
+export type PackageJson =
+PackageJson.PackageJsonStandard &
 PackageJson.NonStandardEntryPoints &
 PackageJson.TypeScriptConfiguration &
 PackageJson.YarnConfiguration &
-PackageJson.JSPMConfiguration & {
-	[key: string]: unknown;
-};
+PackageJson.JSPMConfiguration;

package/source/promise-value.d.ts

@@ -1,5 +1,6 @@
 /**
 Returns the type that is wrapped inside a `Promise` type.
+If the type is a nested Promise, it is unwrapped recursively until a non-Promise type is obtained.
 If the type is not a `Promise`, the type itself is returned.
 
 @example
@@ -15,6 +16,12 @@ let data: Data = await asyncData;
 // Here's an example that shows how this type reacts to non-Promise types.
 type SyncData = PromiseValue<string>;
 let syncData: SyncData = getSyncData();
+
+// Here's an example that shows how this type reacts to recursive Promise types.
+type RecursiveAsyncData = Promise<Promise<string> >;
+let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
 ```
 */
-export type PromiseValue<PromiseType, Otherwise = PromiseType> = PromiseType extends Promise<infer Value> ? Value : Otherwise;
+export type PromiseValue<PromiseType, Otherwise = PromiseType> = PromiseType extends Promise<infer Value>
+	? { 0: PromiseValue<Value>; 1: Value }[PromiseType extends Promise<unknown> ? 0 : 1]
+	: Otherwise;

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

@@ -0,0 +1,29 @@
+type IsAny<T> = 0 extends (1 & T) ? true : false; // https://stackoverflow.com/a/49928360/3406963
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsUnknown<T> = IsNever<T> extends false ? T extends unknown ? unknown extends T ? IsAny<T> extends false ? true : false : false : false : false;
+
+/**
+Create a function type with a return type of your choice and the same parameters as the given function type.
+
+Use-case: You want to define a wrapped function that returns something different while receiving the same parameters. For example, you might want to wrap a function that can throw an error into one that will return `undefined` instead.
+
+@example
+```
+import {SetReturnType} from 'type-fest';
+
+type MyFunctionThatCanThrow = (foo: SomeType, bar: unknown) => SomeOtherType;
+
+type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | undefined>;
+//=> type MyWrappedFunction = (foo: SomeType, bar: unknown) => SomeOtherType | undefined;
+```
+*/
+export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
+	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.
+	Fn extends (this: infer ThisArg, ...args: infer Arguments) => any ? (
+		// 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 ? (...args: Arguments) => TypeToReturn : (this: ThisArg, ...args: Arguments) => TypeToReturn
+	) : (
+		// This part should be unreachable, but we make it meaningful just in case…
+		(...args: Parameters<Fn>) => TypeToReturn
+	);