Add timeout promise function

[aleclarson]

It's like our delay function, but it rejects upon completion.

Usage

await Promise.race([
  someAsyncTask(),
  timeout(1000, "Optional message"),
])

The error looks like this:

Error { name: "TimeoutError", message: "Timed out: Optional message" }

[MarlonPassos-git]

I like the idea. It would be cool to be able to pass a class that extends the Error as a parameter, so that when the error is thrown, we could use our Custom Error. This helps a lot with error handling.

[aleclarson]

Good idea 😄

Which signature should we do?

// A.
timeout(1000, "Optional message", MyError)

// B.
timeout(1000, MyError, "Optional message")

// C.
timeout(1000, () => new MyError("Optional message"))

// D.
timeout(1000, new MyError("Optional message"))

I would say D is out, since constructing errors pre-emptively is generally frowned upon for performance reasons, if I'm not mistaken.

The problem with B is that it requires more runtime type-checking if we also plan to support timeout(1000, "optional message") calls.

Of course, C is bit more verbose, but I'd say it reads nicer than A.

[MarlonPassos-git]

I prefer C.

A and B can limit custom Erros with only one parameter.

[MarlonPassos-git]

#250