Add TypeScript definitions

[tom-sherman]

Closes #74

Pros and cons compared to #85

Pros:

• No need for as many overloads
• Supports as many generics as you like
• Support for as many callback arguments as you like when multiArgs: true. Although not sure if this is in scope in the context of the errorFirst options.

Cons:

• pify((v: number) => {})() returns never instead of erroring. A bit of annoying DX but isn't unsafe.

Todo:

• [ ] Promisifying modules with includes and excludes
• [ ] Document clearly that overloaded functions are not supported and only the final overload will be chosen: https://github.com/microsoft/TypeScript/issues/32164
• [ ] Support excludeMain
• [ ] Support errorFirst

[sindresorhus]

Still interested in finishing this? :)

[tom-sherman]

@sindresorhus Sure! I'll pick this up when I have some time 😄

Just a note, I'm not sure my top todo of "Promisifying modules with includes and excludes" is possible in all cases. Do you have any ideas around that?

My main concern is that you can't get it fully type safe, so any behaviour here will eventually lead to runtime errors. It may be better to just ignore them on a type level.

[sindresorhus]

Just a note, I'm not sure my top todo of "Promisifying modules with includes and excludes" is possible in all cases. Do you have any ideas around that?

In what cases is it not possible?

[sindresorhus]

My main concern is that you can't get it fully type safe, so any behaviour here will eventually lead to runtime errors. It may be better to just ignore them on a type level.

That's fine as long as the cases are documented.

[sindresorhus]

@tom-sherman Friendly bump :)

[tom-sherman]

Now I'm revisiting this it looks like excludes/includes are possible to make safe for the most part. I think even exuding the sync methods by default is possible with template literal types.

[tom-sherman]

@sindresorhus I'm not sure it's possible to support "module functions" here ie. modules with methods. TypeScript doesn't really allow you to work with a type that's callable and also has function properties. We would need to make excludeMain produce never as the return type. What do you think?

The workaround would be to pify each method and the main function separately.

Edit:

I've changed the semantics to be more clear in https://github.com/tom-sherman/pify/commit/4987750dc53d9913a0dc627ed37ec5e304ebdacb

Hopefully this is ok!

[sindresorhus]

Looks good. Thank you :)

[sindresorhus]

@tom-sherman Are you sure there's no way to handle overloads? Because I already hit this problem in multiple places. For example, https://github.com/sindresorhus/got/runs/8157202709?check_suite_focus=true where the overloads are:

export function createCSR(options: CSRCreationOptions, callback: Callback<{ csr: string, clientKey: string }>): void;
export function createCSR(callback: Callback<{ csr: string, clientKey: string }>): void;

This limitation makes it kinda annoying to use pify and the old types (@types/pify) could handle it.

[tom-sherman]

Can you share what the output of pify(createCSR) would be usinng @types/pify? As I understand it you'd just get Promise<any>? If so then @types/pify handles it by not handling it at all, there is very little type safety here.

The issue we have is that there is no easy way to collect all arguments of an overloaded function as a union of tuples, as far as I'm aware. See https://github.com/microsoft/TypeScript/issues/32164

I'll have another read through this issue though, maybe there's a workaround now.

[tom-sherman]

Does the workaround I added to the readme help for you? I get that it's not very ergonomic but should work in all cases.

https://github.com/sindresorhus/pify#why-is-pify-choosing-the-last-function-overload-when-using-it-with-typescript

[sindresorhus]

Does the workaround I added to the readme help for you? I get that it's not very ergonomic but should work in all cases.

Yes, that does work: https://github.com/sindresorhus/got/pull/2120/commits/2cd86007f179abd951cf80fb5bb2d4322b5505a3