Add utility to invoke a function after a delay

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• adds a utility to invoke a function after a delay. In contrast to using setTimeout, which returns a timeout identifier that can be used to clear a pending invocation by calling clearTimeout, the delay function returns a timeout object with additional properties and methods.

Related Issues

Does this pull request have any related issues?

This pull request:

• resolves #
• fixes #

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• [x] Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[github-actions[bot]]

Based off the README.md file, the stdlib-bot has generated contents for the delay package.

Notes

• :warning: The stdlib-bot uses AI to generate package content. The generated content is not guaranteed to be correct, and will require manual review and editing. :warning:

[Planeshifter]

@kgryte Any objections to the API as laid out in the README.md? If not, will implement, clean-up, and push and then ping you for final review.

[kgryte]

Apart from add a note regarding the maximum allowed duration and adding links and a question concerning whether to support human readable duration, this README and proposed API looks good to me.

[github-actions[bot]]

Hi @Planeshifter, thank you for your contribution! Your pull request contains a new package, but is missing some of the required files.

Use the following checklist to keep track of the required files and which ones are still missing:

• [ ] package.json
• [x] README.md
• [ ] docs/repl.txt
• [ ] docs/types/index.d.ts
• [ ] docs/types/test.ts
• [ ] lib/index.js
• [ ] lib/main.js
• [ ] benchmark/benchmark.js
• [ ] examples/index.js
• [ ] test/test.js

Please add the missing files to the pull request.

-- stdlib-bot

[kgryte]

We might also consider adding a CLI to this package, which would achieve something similar to the sleep command (see also https://github.com/sindresorhus/delay-cli/blob/main/cli.js).

Some implementations of sleep support providing suffixes; however, only of one time unit. And some implementations of sleep support providing decimal numbers; however, we shouldn't need to support that provided we support duration strings.

Lastly, the default unit of sleep is seconds. I think we could follow suit. I.e., delay 10 means delay 10 seconds, rather than 10 milliseconds.

[kgryte]

@Planeshifter This looks ready to implement.

[github-actions[bot]]

Based off the README.md file, the stdlib-bot has generated contents for the delay package.

From your local fork, make sure you are on the pull request branch and then merge the changes from the upstream repository:

 git checkout {{ github.event.pull_request.head.ref }}
 git merge upstream/scaffold-547/utils/delay

Notes

• :warning: The stdlib-bot uses AI to generate package content. The generated content is not guaranteed to be correct, and will require manual review and editing. :warning: