type-fest 0.17.0 → 0.18.0

package/index.d.ts

@@ -27,6 +27,8 @@ 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.17.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

@@ -86,6 +86,8 @@ Click the type names for complete docs.
 - [`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/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
+	);