feat: add `timeout` function

[MarlonPassos-git]

[!TIP] The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

This PR introduces a timeout promise function similar to the delay function, but with the ability to reject upon timeout. It also supports custom error classes passing a function as a parameter.

// Rejects after 1 second with the default "timeout" error message
await _.timeout(1000)

// Rejects after 1 second with a custom error message
await _.timeout(1000, 'Custom timeout message')

// Rejects after 1 second with a custom error object
await _.timeout(1000, () => new Error('Custom error'))

Related issue, if any:

203

For any code change,

• [x] Related documentation has been updated, if needed
• [x] Related tests have been added or updated, if needed
• [x] Related benchmarks have been added or updated, if needed

Does this PR introduce a breaking change?

No

Bundle impact

Status	File	Size [^1337]
A	src/async/TimeoutError.ts	127
A	src/async/timeout.ts	246

[^1337]: Function size includes the import dependencies of the function.

[aleclarson]

Hey! There's a new requirement for PRs that introduce new features. Without this requirement met, we won't be able to merge this. Note that this PR can still be included in a beta prerelease before this requirement is fulfilled.

• [ ] Edit the next-minor.md file

⚠️ Note: You need to run git rebase main before this file will appear locally.

[MarlonPassos-git]

@aleclarson about the next-minor.md file, you can check if this is the expected pattern. Maybe we can add some examples in contributing.md to make it easier for new contributors

[aleclarson]

Maybe we can add some examples in contributing.md to make it easier for new contributors

Great idea 👍

This was the expected format:

#### timeout

https://github.com/radashi-org/radashi/pull/250

But using #250 is also acceptable.

The idea is that a script will parse that out and fetch the documentation for each function. The parsing could be relatively loose, so an exact pattern is not strictly required.

If a PR is extending an existing function, I don't know if fetching the related docs will work (or at least, it won't be as easy), so the PR author might be on the hook for describing the new feature in next-minor.md etc.

[radashi-bot]

Benchmark Results

Name	Current
timeout: with default error message	921.57 ops/sec ±0.41%
timeout: with custom error message	920.74 ops/sec ±0.42%
timeout: with custom error function	925.63 ops/sec ±0.74%

Performance regressions of 30% or more should be investigated, unless they were anticipated. Smaller regressions may be due to normal variability, as we don't use dedicated CI infrastructure.

[aleclarson]

We don't benchmark async functions (or at least, we haven't been).

[aleclarson]

Thanks for everything, Marlon! 🚀

[radashi-bot]

A stable release 12.3.0 has been published to NPM. :rocket:

To install:

pnpm add radashi@12.3.0