Add Types

[Ethan-Arrowood]

Ready for review! 🌟 This should get us started on types. Keeping as draft until branch is at v1 parity. Other's are welcome to contribute types as well (@delvedor). Please pr to my fork's types branch with whatever additions/modifications you make.

I'm pretty confident with the index.d.ts file exports. I spent a good deal of time researching and this seems the most correct. Other TS folk please feel free to review and provide suggestions if improvements can be made ❤️

Closes #289

[Ethan-Arrowood]

Working on Errors now. I think I found a good pattern that will also support proper type guarding 😄

~ edit ~

😉

import { Errors } from 'undici'
{
	function f (): Errors.HeadersTimeoutError | Errors.SocketTimeoutError { return }

	const e = f()

	if (e.code === 'UND_ERR_HEADERS_TIMEOUT') {
		expectAssignable<Errors.HeadersTimeoutError>(e)
	} else if (e.code === 'UND_ERR_SOCKET_TIMEOUT') {
		expectAssignable<Errors.SocketTimeoutError>(e)
	}
}

[ronag]

@Ethan-Arrowood do you intend to continue on this?

[Ethan-Arrowood]

I've been focusing on trying to finish the iterable body feature, but since I'm not making much progress there I can shift my focus to finishing these up. Do you think we should publish these types here or in definitely typed?

[Ethan-Arrowood]

And like that, this is ready for review!

I mainly relied on the README file for details.

Some questions:

• Should I restrict method to the union of the standard HTTP methods, all uppercase? ('GET' | 'POST' | ...)
• Is client.dispatch actually able to return a Promise?
• What is opaque? I used the unknown type rather than any so the types are as safe as possible.
• Are any of the dispatch handlers required? They are all currently set as optional
• I can't remember where I copied the list of Headers from, but is this list defined somewhere? Potentially apart of the existing Node.js types?

[mcollina]

I'll let @ronag respond about dispatch().

---

• Should I restrict method to the union of the standard HTTP methods, all uppercase? ('GET' | 'POST' | ...)

Yes, but there are a lot of those (http.METHODS is your friend).

• What is opaque? I used the unknown type rather than any so the types are as safe as possible.

It allows the developer to not create a closure. It's passed through to the function. It's a C/C++ technique used in libuv and a lot of other places. unknown is ok. You might also want to use a generic here.

• I can't remember where I copied the list of Headers from, but is this list defined somewhere? Potentially apart of the existing Node.js types?

I'm lost. Headers are just strings and there are known headers. I don't know about Node.js types for those.

[Ethan-Arrowood]

Yes, but there are a lot of those (http.METHODS is your friend).

Okay will do.

It allows the developer to not create a closure. It's passed through to the function. It's a C/C++ technique used in libuv and a lot of other places. unknown is ok. You might also want to use a generic here.

I was also thinking about using a generic. I'll try and do a bit more research on what it is and see if I can come up with. a better type

I'm lost. Headers are just strings and there are known headers. I don't know about Node.js types for those.

Yeah in other parts of the types where headers is an array rather than a key/value object, I used string[]. I'm wondering if its better to make the key/value object into Record<string, string> instead since then at least we wont ever be missing a header from the types. I'll also peek into the Node.js types again and see if there is something inside of http or wherever

[ronag]

Is client.dispatch actually able to return a Promise?

Nope.

[Ethan-Arrowood]

Should I restrict method to the union of the standard HTTP methods, all uppercase? ('GET' | 'POST' | ...)

Answer: no. Technically a method can be any string. If someone really wanted to they could create custom methods

Is client.dispatch actually able to return a Promise?

Answer: no. Will remove the typing now and fix the readme too

What is opaque? I used the unknown type rather than any so the types are as safe as possible.

For simplicity, I'm keeping this as unknown. Using a generic to pass through a type is no safer than type casting an unknown value.

Are any of the dispatch handlers required? They are all currently set as optional

@ronag ^

I can't remember where I copied the list of Headers from, but is this list defined somewhere? Potentially apart of the existing Node.js types?

Its defined inside node http types as IncomingRequestHeaders. I've switched over to using that now. I'm still tempted to replace it with Record<string, string> as headers can also be custom. I'd like some more input on this from other Node.js/TypeScript devs.

[Ethan-Arrowood]

I don't know if it matters too much but two of my previous commits weren't GPG signed. I've amended the latest one.

[mcollina]

lgtm, I think we can land this now.

[RafaelGSS]

LGTM.